# 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. ``` ##### Showing all disallowed privileges By default, Authz plugin checks required privileges one by one and throw the first unsatisfied privilege in exception. By setting `ranger.plugin.spark.authorize.in.single.call` to `true`, Authz plugin executes access checks in single call and throws all disallowed privileges in exception message. ```xml ranger.plugin.spark.authorize.in.single.call true Enable access checks in single call with all disallowed privileges thrown in exception. Default value is false. ``` #### 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 ```