Basic server access control (unitycatalog#378)

**PR Checklist**

- [ ] A description of the changes is added to the description of this
PR.
- [ ] If there is a related issue, make sure it is linked to this PR.
- [ ] If you've fixed a bug or added code that should be tested, add
tests!
- [ ] If you've added or modified a feature, documentation in `docs` is
updated

**Description of changes**

This feature builds upon the authentication functionality to add access
controls to UC server endpoints.

- Access control is optionally enabled through server server
configuration (`server.authorization=enable`)
- Resource endpoints all have access control rules that match access
rules for Databricks Unity Catalog.
- An access control is defined by a principal, a resource and a
privilege.
- Principals are currently only user entities.
- Access controls are hierarchically applied - A privilege assigned to a
resource for a principal is active for all the children.
- A command-line interface is available to add, update, and delete
authorizations.
- The root of the hierarchy is a catalog.
- There is a new concept of a metastore, which is primarily a resource
to assign server level privileges with.

The initial set of privileges defined are
- `CREATE CATALOG` - allows the principal to create catalogs
- `USE CATALOG` - allows the principal to access/use a catalog
- `CREATE SCHEMA` - allows the principal to create schemas within a
catalog
- `USE SCHEMA` - allows the principal to access/use the schema and child
tables
- `CREATE_TABLE` - allows the principal to create tables in the schema
- `SELECT` - allows the principal to run queries against table(s)
- `CREATE_FUNCTION` - allows principal to create functions in the schema
- `EXECUTE` - allows the principal to execute function(s)
- `CREATE_VOLUME` - allows principal to create volumes in the schema
- `READ VOLUME` - allows the principal to access volumes within the
catalog
- `CREATE MODEL` - allows the principal to create models within a schema

The rules are generally more complex than summarized above, check
Databricks documentation or the code for more details.

The CLI interface provides a new `permission` command. Examples

```
bin/uc permission create --securable_type catalog \
  --name mycatalog --principal [email protected] --privilege "CREATE CATALOG`

bin/uc  permission get --securable_type catalog --name unity

binuc permission delete --securable_type table \
  --name mycatalog.myschema.table --principal [email protected] --privilege SELECT
```

The framework attempts to separate the concern of access control from
the rest of the request handling and processing through annotation-based
configuration, via `@AuthorizeExpression`, `@AuthorizeKey` and
`@AuthorizeKeys` added to each service entry point. All requests are
routed through the `UnityAccessDecorator` which decodes the request,
parameters and authorization configuration to evaluate whether access
should be allowed or denied.

---------

Co-authored-by: Vikrant Puppala <[email protected]>
Co-authored-by: Vikrant Puppala <[email protected]>
Co-authored-by: Xiang Xu <[email protected]>

Author: 3 people

api/all.yaml

@@ -32,6 +32,9 @@ tags:
   - name: TemporaryCredentials
     description: |
       Temporary credentials are used to access storage locations or assets for a limited lifetime.
+  - name: Permissions
+    description: |
+      In Unity Catalog, data is secure by default. Access can be granted.
 paths:
   /catalogs:
     post:
@@ -1056,6 +1059,61 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/TemporaryCredentials'
+  /permissions/{securable_type}/{full_name}:
+    parameters:
+      - name: securable_type
+        in: path
+        description: Type of securable.
+        required: true
+        schema:
+          $ref: '#/components/schemas/SecurableType'
+      - name: full_name
+        in: path
+        description: Full name of securable.
+        required: true
+        schema:
+          type: string
+    get:
+      tags:
+        - Grants
+      parameters:
+        - name: principal
+          in: query
+          description: |
+            If provided, only the permissions for the specified principal (user or group) are returned.
+          schema:
+            type: string
+          required: false
+      operationId: get
+      summary: Get permissions
+      description: |
+        Gets the permissions for a securable.
+      responses:
+        '200':
+          description: The permissions list for securable was successfully retrieved.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PermissionsList'
+    patch:
+      tags:
+        - Grants
+      operationId: update
+      summary: Update a permission
+      description: |
+        Updates the permissions for a securable.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdatePermissions'
+      responses:
+        '200':
+          description: The permissions list for securable was successfully updated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PermissionsList'
 components:
   schemas:
     SecurablePropertiesMap:
@@ -2145,6 +2203,92 @@ components:
         - PATH_CREATE_TABLE
         - PATH_REFRESH
       type: string
+    PrincipalType:
+      type: string
+      enum:
+        - USER
+        - GROUP
+      description: The type of the principal.
+    SecurableType:
+      type: string
+      enum:
+        - metastore
+        - catalog
+        - schema
+        - table
+        - function
+        - volume
+        - registered_model
+      description: The type of the resource.
+    Privilege:
+      type: string
+      enum:
+        - CREATE CATALOG
+        - USE CATALOG
+        - CREATE SCHEMA
+        - USE SCHEMA
+        - CREATE TABLE
+        - SELECT
+        - CREATE FUNCTION
+        - EXECUTE
+        - CREATE VOLUME
+        - READ VOLUME
+        - CREATE MODEL
+      description: The privilege to grant.
+    UpdatePermissions:
+      type: object
+      properties:
+        changes:
+          description: Array of permissions change objects.
+          type: array
+          items:
+            $ref: '#/components/schemas/PermissionsChange'
+      required:
+        - changes
+    PermissionsChange:
+      type: object
+      properties:
+        principal:
+          description: The principal whose privileges we are changing.
+          type: string
+        add:
+          description: The set of privileges to add.
+          type: array
+          items:
+            $ref: '#/components/schemas/Privilege'
+        remove:
+          description: The set of privileges to remove.
+          type: array
+          items:
+            $ref: '#/components/schemas/Privilege'
+      required:
+        - principal
+        - add
+        - remove
+    PermissionsList:
+      type: object
+      properties:
+        privilege_assignments:
+          description: The privileges assigned to each principal.
+          type: array
+          items:
+            $ref: '#/components/schemas/PrivilegeAssignment'
+      required:
+        - privilege_assignments
+    PrivilegeAssignment:
+      type: object
+      properties:
+        principal:
+          description: The principal (user email address or group name).
+          type: string
+        privileges:
+          description: The privileges assigned to the principal.
+          type: array
+          items:
+            $ref: '#/components/schemas/Privilege'
+      required:
+        - principal
+        - privileges
 info:
   title: Unity Catalog API
   version: '0.1'

build.sbt

@@ -84,6 +84,7 @@ lazy val commonSettings = Seq(
     case DepModuleInfo("org.hibernate.orm", _, _) => true
     case DepModuleInfo("com.unboundid.scim2", _, _) => true
     case DepModuleInfo("com.unboundid.product.scim2", _, _) => true
+    case DepModuleInfo("com.googlecode.aviator", _, _) => true
     // Duo license:
     //  - Eclipse Public License 2.0
     //  - GNU General Public License, version 2 with the GNU Classpath Exception
@@ -301,6 +302,10 @@ lazy val server = (project in file("server"))
 
       // Auth dependencies
       "com.unboundid.product.scim2" % "scim2-sdk-common" % "3.1.0",
+      "org.casbin" % "jcasbin" % "1.55.0",
+      "org.casbin" % "jdbc-adapter" % "2.7.0"
+        exclude("com.microsoft.sqlserver", "mssql-jdbc")
+        exclude("com.oracle.database.jdbc", "ojdbc6"),
       "org.springframework" % "spring-expression" % "6.1.11",
       "com.auth0" % "java-jwt" % "4.4.0",
       "com.auth0" % "jwks-rsa" % "0.22.1",

examples/cli/src/main/java/io/unitycatalog/cli/PermissionCli.java

@@ -0,0 +1,82 @@
+package io.unitycatalog.cli;
+
+import static io.unitycatalog.cli.utils.CliUtils.*;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import io.unitycatalog.cli.utils.CliParams;
+import io.unitycatalog.cli.utils.CliUtils;
+import io.unitycatalog.client.ApiClient;
+import io.unitycatalog.client.ApiException;
+import io.unitycatalog.client.api.GrantsApi;
+import io.unitycatalog.client.model.PermissionsChange;
+import io.unitycatalog.client.model.Privilege;
+import io.unitycatalog.client.model.SecurableType;
+import io.unitycatalog.client.model.UpdatePermissions;
+import java.util.List;
+import org.apache.commons.cli.CommandLine;
+import org.json.JSONObject;
+
+public class PermissionCli {
+  private static ObjectWriter objectWriter;
+
+  public static void handle(CommandLine cmd, ApiClient apiClient)
+      throws JsonProcessingException, ApiException {
+    GrantsApi grantsApi = new GrantsApi(apiClient);
+    String[] subArgs = cmd.getArgs();
+    objectWriter = CliUtils.getObjectWriter(cmd);
+    String subCommand = subArgs[1];
+    JSONObject json = CliUtils.createJsonFromOptions(cmd);
+    String output = EMPTY;
+    switch (subCommand) {
+      case CREATE:
+      case DELETE:
+        output = updatePermission(grantsApi, json, subCommand);
+        break;
+      case GET:
+        output = getPermission(grantsApi, json);
+        break;
+      default:
+        printEntityHelp(PERMISSION);
+    }
+    postProcessAndPrintOutput(cmd, output, subCommand);
+  }
+
+  private static String updatePermission(GrantsApi grantsApi, JSONObject json, String subCommand)
+      throws JsonProcessingException, ApiException {
+    SecurableType securableType =
+        SecurableType.fromValue(json.getString(CliParams.SECURABLE_TYPE.getServerParam()));
+    String name = json.getString(CliParams.NAME.getServerParam());
+    List<Privilege> add =
+        subCommand.equals(CREATE)
+            ? List.of(Privilege.fromValue(json.getString(CliParams.PRIVILEGE.getServerParam())))
+            : List.of();
+    List<Privilege> remove =
+        subCommand.equals(DELETE)
+            ? List.of(Privilege.fromValue(json.getString(CliParams.PRIVILEGE.getServerParam())))
+            : List.of();
+    PermissionsChange permissionsChange =
+        new PermissionsChange()
+            .principal(json.getString(CliParams.PRINCIPAL.getServerParam()))
+            .add(add)
+            .remove(remove);
+    UpdatePermissions updatePermissions =
+        new UpdatePermissions().changes(List.of(permissionsChange));
+
+    return objectWriter.writeValueAsString(
+        grantsApi.update(securableType, name, updatePermissions).getPrivilegeAssignments());
+  }
+
+  private static String getPermission(GrantsApi grantsApi, JSONObject json)
+      throws JsonProcessingException, ApiException {
+    SecurableType securableType =
+        SecurableType.fromValue(json.getString(CliParams.SECURABLE_TYPE.getServerParam()));
+    String name = json.getString(CliParams.NAME.getServerParam());
+    String principal = null;
+    if (json.has(CliParams.PRINCIPAL.getServerParam())) {
+      principal = json.getString(CliParams.PRINCIPAL.getServerParam());
+    }
+    return objectWriter.writeValueAsString(
+        grantsApi.get(securableType, name, principal).getPrivilegeAssignments());
+  }
+}

examples/cli/src/main/java/io/unitycatalog/cli/UnityCatalogCli.java

@@ -144,6 +144,9 @@ public static void main(String[] args) {
         case CliUtils.MODEL_VERSION:
           ModelVersionCli.handle(cmd, apiClient);
           break;
+        case CliUtils.PERMISSION:
+          PermissionCli.handle(cmd, apiClient);
+          break;
         case CliUtils.USER:
           UserCli.handle(cmd, getControlClient(cmd));
           break;

examples/cli/src/main/java/io/unitycatalog/cli/utils/CliParams.java

@@ -52,17 +52,15 @@ public enum CliParams {
       "output"),
   VERSION("version", "Version number of a registered model entity.", "version"),
   FORCE("force", "To force delete the entity", "force"),
-  RESOURCE_TYPE("resource_type", "The type of the resource", "resource_type"),
+  SECURABLE_TYPE("securable_type", "The type of the securable", "securable_type"),
   PRINCIPAL("principal", "The target principal of the permission change", "principal"),
   PRIVILEGE("privilege", "The privilege to grant or revoke", "privilege"),
   ID("id", "The unique id of the user", "id"),
   EXTERNAL_ID("external_id", "The identity provider's id for the user", "externalId"),
   EMAIL("email", "The email address for the user", "email"),
   FILTER("filter", "Query by which the results have to be filtered", "filter"),
   START_INDEX(
-      "startIndex",
-      "Specifies the index of the first result. First item is number 1",
-      "startIndex"),
+      "start_index", "Specifies the index (starting at 1) of the first result.", "startIndex"),
   COUNT("count", "Desired number of results per page", "count");
   private final String value;
   private final String helpMessage;

examples/cli/src/main/java/io/unitycatalog/cli/utils/CliUtils.java

@@ -33,6 +33,7 @@ public class CliUtils {
   public static final String FUNCTION = "function";
   public static final String REGISTERED_MODEL = "registered_model";
   public static final String MODEL_VERSION = "model_version";
+  public static final String PERMISSION = "permission";
   public static final String USER = "user";
   public static final String CREATE = "create";
   public static final String LIST = "list";
@@ -277,6 +278,35 @@ public List<CliParams> getOptionalParams() {
                   put(DELETE, new CliOptions(List.of(CliParams.ID), List.of()));
                 }
               });
+          put(
+              PERMISSION,
+              new HashMap<String, CliOptions>() {
+                {
+                  put(
+                      CREATE,
+                      new CliOptions(
+                          List.of(
+                              CliParams.SECURABLE_TYPE,
+                              CliParams.NAME,
+                              CliParams.PRINCIPAL,
+                              CliParams.PRIVILEGE),
+                          List.of()));
+                  put(
+                      DELETE,
+                      new CliOptions(
+                          List.of(
+                              CliParams.SECURABLE_TYPE,
+                              CliParams.NAME,
+                              CliParams.PRINCIPAL,
+                              CliParams.PRIVILEGE),
+                          List.of()));
+                  put(
+                      GET,
+                      new CliOptions(
+                          List.of(CliParams.SECURABLE_TYPE, CliParams.NAME),
+                          List.of(CliParams.PRINCIPAL)));
+                }
+              });
         }
       };