# Installing and Configuring Kyuubi Spark AuthZ Plugin
## Pre-install
- [Apache Ranger](https://ranger.apache.org/)
This plugin works as a ranger rest client with Apache Ranger admin server to do privilege check.
Thus, a ranger server need to be installed ahead and available to use.
- Building(optional)
If your ranger admin or spark distribution is not compatible with the official pre-built [artifact](https://mvnrepository.com/artifact/org.apache.kyuubi/kyuubi-spark-authz) in maven central.
You need to [build](build.md) the plugin targeting the spark/ranger you are using by yourself.
## Install
With the `kyuubi-spark-authz_*.jar` and its transitive dependencies available for spark runtime classpath, such as
- Copied to `$SPARK_HOME/jars`, or
- Specified to `spark.jars` configuration
## Configure
### Settings for Connecting Ranger Admin
#### ranger-spark-security.xml
- Create `ranger-spark-security.xml` in `$SPARK_HOME/conf` and add the following configurations
for pointing to the right Ranger admin server.
```xml
ranger.plugin.spark.policy.rest.url
ranger admin address like http://ranger-admin.org:6080
ranger.plugin.spark.service.name
a ranger hive service name
ranger.plugin.spark.policy.cache.dir
./a ranger hive service name/policycache
ranger.plugin.spark.policy.pollIntervalMs
5000
ranger.plugin.spark.policy.source.impl
org.apache.ranger.admin.client.RangerAdminRESTClient
```
##### Using Macros in Row Level Filters
Macros are now supported for using user/group/tag in row filter expressions, introduced in [Ranger 2.3](https://cwiki.apache.org/confluence/display/RANGER/Apache+Ranger+2.3.0+-+Release+Notes). This feature helps significantly simplify row filter expressions by using user/group/tag's attributes instead of explicit conditions. Considering a user with an attribute `born_city` of value `Guangzhou `, the row filter condition as `city='${{USER.born_city}}'` will be transformed to `city='Guangzhou'` in execution plan. More supported macros and usage refer to [RANGER-3605](https://issues.apache.org/jira/browse/RANGER-3605) and [RANGER-3550](https://issues.apache.org/jira/browse/RANGER-3550). Add the following configs to `ranger-spark-security.xml` to enable UserStore Enricher required by macros.
```xml
ranger.plugin.spark.enable.implicit.userstore.enricher
true
Enable UserStoreEnricher for fetching user and group attributes if using macros or scripts in row-filters since Ranger 2.3
ranger.plugin.hive.policy.cache.dir
./a ranger hive service name/policycache
As Authz plugin reuses hive service def, a policy cache path is required for caching UserStore and Tags for "hive" service def, while "ranger.plugin.spark.policy.cache.dir config" is the path for caching policies in service.
```
#### ranger-spark-audit.xml
Create `ranger-spark-audit.xml` in `$SPARK_HOME/conf` and add the following configurations
to enable/disable auditing.
```xml
xasecure.audit.is.enabled
true
xasecure.audit.destination.db
false
xasecure.audit.destination.db.jdbc.driver
com.mysql.jdbc.Driver
xasecure.audit.destination.db.jdbc.url
jdbc:mysql://10.171.161.78/ranger
xasecure.audit.destination.db.password
rangeradmin
xasecure.audit.destination.db.user
rangeradmin
```
### Settings for Spark Session Extensions
Add `org.apache.kyuubi.plugin.spark.authz.ranger.RangerSparkExtension` to the spark configuration `spark.sql.extensions`.
```properties
spark.sql.extensions=org.apache.kyuubi.plugin.spark.authz.ranger.RangerSparkExtension
```