TemporaryPathCredentialsService, Credential Vending and Basic Server Access Control

Author: jaceklaskowski

docs/basic-server-access-control/index.md

@@ -20,7 +20,7 @@
 
 ## Securables
 
-Unity Catalog supports the following types of securables to apply (_create_) permissions to:
+Unity Catalog defines the following securables to apply (_create_) permissions to:
 
 1. `catalog`
 1. `function`
@@ -30,24 +30,40 @@ Unity Catalog supports the following types of securables to apply (_create_) per
 1. `table`
 1. `volume`
 
+??? note "OpenAPI Generator"
+    Securable types are defined in `SecurableType` enum in Unity Catalog's [OpenAPI specification]({{ uc.github }}/api/all.yaml).
+
+## Principals
+
+There are the following principal types supported in Unity Catalog:
+
+* `USER`
+* `GROUP`
+
+??? note "OpenAPI Generator"
+    Principals are defined in `PrincipalType` enum in Unity Catalog's [OpenAPI specification]({{ uc.github }}/api/all.yaml).
+
 ## Privileges
 
-The initial set of privileges are as follows:
+The privileges to grant are as follows:
 
 Privilege | Description
 -|-
  `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
+ `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
+ `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
+ `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
 
+??? note "OpenAPI Generator"
+    Privileges are defined in `Privilege` enum in Unity Catalog's [OpenAPI specification]({{ uc.github }}/api/all.yaml).
+
 ## Unity Catalog CLI
 
 The CLI interface provides a new [permission](../cli/PermissionCli.md) command.

docs/credential-vending/index.md

@@ -23,6 +23,20 @@ Credential Vending supports the following privileges:
 ??? note "Permissions"
     Privileges is a synonym of Permissions.
 
+## Path Operations
+
+There are the following path operations supported in Unity Catalog:
+
+* `PATH_CREATE_TABLE`
+* `PATH_READ`
+* `PATH_READ_WRITE`
+* `UNKNOWN_PATH_OPERATION`
+
+The path operations are used for [TemporaryPathCredentialsService](../server/TemporaryPathCredentialsService.md) to determine the [privileges for a path operation](../server/TemporaryPathCredentialsService.md#pathOperationToPrivileges) (while [generating temporary path credentials](../server/TemporaryPathCredentialsService.md#generateTemporaryPathCredential)).
+
+??? note "OpenAPI Generator"
+    Path operations are defined in `PathOperation` enum in Unity Catalog's [OpenAPI specification]({{ uc.github }}/api/all.yaml).
+
 ## Amazon S3
 
 [Alex Reid once wrote]({{ uc.slack }}/C076YREKX8W/p1728333073156489?thread_ts=1728308961.254459&cid=C076YREKX8W):

docs/server/TableService.md

@@ -1,6 +1,6 @@
 # TableService
 
-`TableService` is a Unity Catalog API service that [UnityCatalogServer](UnityCatalogServer.md) uses to handle HTTP requests at `/api/2.1/unity-catalog/tables` URL.
+`TableService` is an API service that [UnityCatalogServer](UnityCatalogServer.md) uses to handle HTTP requests at `/api/2.1/unity-catalog/tables` URL.
 
 Method | URL | Handler | Params
 -|-|-|-

docs/server/TemporaryPathCredentialsService.md

@@ -1,5 +1,44 @@
 # TemporaryPathCredentialsService
 
+`TemporaryPathCredentialsService` is an API service of [UnityCatalogServer](UnityCatalogServer.md) to handle HTTP requests at `/api/2.1/unity-catalog/temporary-path-credentials` URL.
+
+Method | URL | Handler | Params
+-|-|-|-
+ POST | `/` | [generateTemporaryPathCredential](#generateTemporaryPathCredential) | JSON-ified `GenerateTemporaryPathCredential`
+
+`TemporaryPathCredentialsService` handles `POST` requests only with the following authorization guarantees:
+
+Method | AuthorizeExpression | Securables
+-|-|-
+ POST | [authorize(#principal, #metastore, OWNER)](../server-authorization/AuthorizeExpression.md) | [METASTORE](../basic-server-access-control/index.md#securables)
+
+## Demo
+
+!!! note "etc/conf/server.properties"
+    The following demo requires `url` being configured in [etc/conf/server.properties](index.md#server-configuration) (using`s3.bucketPath.0=s3://uc-japila` and the others).
+
+```console
+$ http http://localhost:8081/api/2.1/unity-catalog/temporary-path-credentials \
+    url=s3://uc-japila \
+    operation=PATH_CREATE_TABLE
+HTTP/1.1 200 OK
+content-length: 1198
+content-type: application/json
+date: Sat, 2 Nov 2024 19:51:29 GMT
+server: Armeria/1.28.4
+
+{
+    "aws_temp_credentials": {
+        "access_key_id": "xxx",
+        "secret_access_key": "xxx",
+        "session_token": "xxx"
+    },
+    "azure_user_delegation_sas": null,
+    "expiration_time": null,
+    "gcp_oauth_token": null
+}
+```
+
 ## Creating Instance
 
 `TemporaryPathCredentialsService` takes the following to be created:
@@ -17,4 +56,23 @@ HttpResponse generateTemporaryPathCredential(
   GenerateTemporaryPathCredential generateTemporaryPathCredential)
 ```
 
-`generateTemporaryPathCredential`...FIXME
+`generateTemporaryPathCredential` requests this [CredentialOperations](#credentialOps) to [vendCredential](../credential-vending/CredentialOperations.md#vendCredential) for the `url` and `operation` properties (of the given `GenerateTemporaryPathCredential`).
+
+!!! note "Internal Server Error"
+    `operation` should be one of the [supported path operations](../credential-vending/index.md#path-operations) or Unity Catalog reports an internal error.
+
+### Privileges by Path Operation { #pathOperationToPrivileges }
+
+```java
+Set<CredentialContext.Privilege> pathOperationToPrivileges(
+  PathOperation pathOperation)
+```
+
+`pathOperationToPrivileges` converts the given [PathOperation](../credential-vending/index.md#path-operations) to [Privileges](../basic-server-access-control/index.md#privileges):
+
+PathOperation | Privileges
+-|-
+ `PATH_READ` | `SELECT`
+ `PATH_READ_WRITE` | `SELECT` and `UPDATE`
+ `PATH_CREATE_TABLE` | `SELECT` and `UPDATE`
+ `UNKNOWN_PATH_OPERATION` | (empty)