UnityAccessDecorator, UnityAccessEvaluator and UnityCatalogAuthorizer

docs/persistent-storage/MetastoreRepository.md

@@ -0,0 +1,3 @@
+# MetastoreRepository
+
+`MetastoreRepository` is...FIXME

docs/server-authorization/KeyMapperUtil.md

@@ -0,0 +1,39 @@
+# KeyMapperUtil
+
+## Resolve Resource Names Into IDs { #mapResourceKeys }
+
+``` java
+Map<SecurableType, Object> mapResourceKeys(
+  Map<SecurableType, Object> resourceKeys)
+```
+
+??? note "Static Method"
+    `mapResourceKeys` is a Java **class method** to be invoked without a reference to a particular object.
+
+    Learn more in the [Java Language Specification]({{ java.spec }}/jls-8.html#jls-8.4.3.2).
+
+`mapResourceKeys` resolves the given `SecurableType`s with their names (`resourceKeys`) into `SecurableType`s with IDs (in the given order).
+
+ Resource Keys | SecurableType | ID | Repository
+-|-|-|-
+ CATALOG, SCHEMA, TABLE | TABLE | `table_id` | [TableRepository](../persistent-storage/TableRepository.md#getTable)
+ TABLE<br>(with neither CATALOG nor SCHEMA) | TABLE<br>SCHEMA<br>CATALOG | `table_id`<br>`schema_id`<br>`id` | [TableRepository](../persistent-storage/TableRepository.md#getTable)<br>[SchemaRepository](../persistent-storage/SchemaRepository.md#getSchema)<br>[CatalogRepository](../persistent-storage/CatalogRepository.md#getCatalog)
+ CATALOG, SCHEMA, VOLUME | VOLUME | `volume_id` | [VolumeRepository](../persistent-storage/VolumeRepository.md#getVolume)
+ VOLUME<br>(with neither CATALOG nor SCHEMA) | &nbsp; | &nbsp; | &nbsp;
+ CATALOG, SCHEMA, FUNCTION | &nbsp; | &nbsp; | &nbsp;
+ FUNCTION<br>(with neither CATALOG nor SCHEMA) | &nbsp; | &nbsp; | &nbsp;
+ CATALOG, SCHEMA, REGISTERED_MODEL | &nbsp; | &nbsp; | &nbsp;
+ REGISTERED_MODEL<br>(with neither CATALOG nor SCHEMA) | &nbsp; | &nbsp; | &nbsp;
+ CATALOG, SCHEMA | SCHEMA | `schema_id` | [SchemaRepository](../persistent-storage/SchemaRepository.md#getSchema)
+ SCHEMA<br>(with no CATALOG) | SCHEMA<br>CATALOG | `schema_id`<br>`id` | [SchemaRepository](../persistent-storage/SchemaRepository.md#getSchema)<br>[CatalogRepository](../persistent-storage/CatalogRepository.md#getCatalog)
+ CATALOG | CATALOG | `id` | [CatalogRepository](../persistent-storage/CatalogRepository.md#getCatalog)
+ METASTORE | METASTORE | `ca7a1095-537c-4f9c-a136-5ca1ab1ec0de` | [MetastoreRepository](../persistent-storage/MetastoreRepository.md#getMetastoreId)
+
+---
+
+`mapResourceKeys` is used when:
+
+* `UnityAccessDecorator` is requested to [check authorization](UnityAccessDecorator.md#checkAuthorization)
+* `TemporaryModelVersionCredentialsService` is requested to [authorizeForOperation](../server/TemporaryModelVersionCredentialsService.md#authorizeForOperation)
+* `TemporaryTableCredentialsService` is requested to [authorizeForOperation](../server/TemporaryTableCredentialsService.md#authorizeForOperation)
+* `TemporaryVolumeCredentialsService` is requested to [authorizeForOperation](../server/TemporaryVolumeCredentialsService.md#authorizeForOperation)

docs/server-authorization/UnityAccessDecorator.md

@@ -133,15 +133,39 @@ void checkAuthorization(
   Map<SecurableType, Object> resourceKeys)
 ```
 
-`checkAuthorization`...FIXME
+In essence, `checkAuthorization` reports a `BaseException` to indicate "Access denied". Otherwise, authorization is granted.
+
+---
+
+`checkAuthorization` prints out the following DEBUG message to the logs:
+
+``` text
+resourceKeys = [resourceKeys]
+```
+
+`checkAuthorization` [resolves resource names into IDs](KeyMapperUtil.md#mapResourceKeys).
+
+`checkAuthorization` prints out the following DEBUG message to the logs:
+
+``` text
+resourceIds = [resourceIds]
+```
+
+`checkAuthorization` requests the [UnityAccessEvaluator](#evaluator) to [evaluate](UnityAccessEvaluator.md#evaluate) with the given `principal`, `expression` and the resolved resource IDs.
+
+In case when the `UnityAccessEvaluator` does not evaluate the expression for the `principal` and the resource IDs successfully, `checkAuthorization` reports a `BaseException` with the following message:
+
+``` text
+Access denied.
+```
 
 ## Logging
 
 Enable `ALL` logging level for `io.unitycatalog.server.auth.decorator.UnityAccessDecorator` logger to see what happens inside.
 
 Add the following line to `etc/conf/server.log4j2.properties`:
 
-```text
+``` text
 logger.UnityAccessDecorator.name = io.unitycatalog.server.auth.decorator.UnityAccessDecorator
 logger.UnityAccessDecorator.level = all
 ```

docs/server-authorization/UnityAccessEvaluator.md

@@ -1,3 +1,66 @@
 # UnityAccessEvaluator
 
-`UnityAccessEvaluator` is...FIXME
+## Evaluate Authorization Expression { #evaluate }
+
+``` java
+boolean evaluate(
+  UUID principal,
+  String expression,
+  Map<SecurableType, Object> resourceIds)
+```
+
+`evaluate` returns whatever the given `expression` has been evaluated to for the given `principal` and the resource IDs.
+
+---
+
+`evaluate` creates a `StandardEvaluationContext` (Spring Expression Language) with `Privileges` root object.
+
+`evaluate` registers the following functions in the `StandardEvaluationContext`:
+
+Function | Handler
+-|-
+authorize | [authorizeHandle](UnityCatalogAuthorizer.md#authorize)
+authorizeAny | [authorizeAnyHandle](UnityCatalogAuthorizer.md#authorizeAny)
+authorizeAll | [authorizeAllHandle](UnityCatalogAuthorizer.md#authorizeAll)
+
+`evaluate` sets the following variables in the `StandardEvaluationContext`:
+
+Variable | Value
+-|-
+ deny | FALSE
+ permit | TRUE
+ defer | TRUE
+ principal | The given `principal`
+
+`evaluate` sets variables (in the `StandardEvaluationContext`) for every resource ID (in the given `resourceIds`).
+
+`evaluate` requests this [ExpressionParser](#parser) to evaluate the expression (in the `StandardEvaluationContext`).
+
+`evaluate` prints out the following DEBUG message to the logs:
+
+``` text
+evaluating [expression] = [result]
+```
+
+---
+
+`evaluate` is used when:
+
+* `UnityAccessDecorator` is requested to [check authorization](UnityAccessDecorator.md#checkAuthorization)
+* `UnityAccessEvaluator` is requested to [filter](#filter)
+* `TemporaryModelVersionCredentialsService` is requested to [authorizeForOperation](../server/TemporaryModelVersionCredentialsService.md#authorizeForOperation)
+* `TemporaryTableCredentialsService` is requested to [authorizeForOperation](../server/TemporaryTableCredentialsService.md#authorizeForOperation)
+* `TemporaryVolumeCredentialsService` is requested to [authorizeForOperation](../server/TemporaryVolumeCredentialsService.md#authorizeForOperation)
+
+## Logging
+
+Enable `ALL` logging level for `io.unitycatalog.server.auth.decorator.UnityAccessEvaluator` logger to see what happens inside.
+
+Add the following line to `etc/conf/server.log4j2.properties`:
+
+``` text
+logger.UnityAccessEvaluator.name = io.unitycatalog.server.auth.decorator.UnityAccessEvaluator
+logger.UnityAccessEvaluator.level = all
+```
+
+Refer to [Logging](../logging.md).

docs/server-authorization/UnityCatalogAuthorizer.md

@@ -22,6 +22,40 @@ Used when:
 * `PermissionService` is requested for the [authorizations](../server/PermissionService.md#getAuthorization)
 * `UnityAccessEvaluator` is [created](UnityAccessEvaluator.md#authorizeHandle)
 
+### Authorize All Privileges { #authorizeAll }
+
+``` java
+boolean authorizeAll(
+  UUID principal,
+  UUID resource,
+  Privileges... actions)
+```
+
+See:
+
+* [JCasbinAuthorizer](JCasbinAuthorizer.md#authorizeAll)
+
+Used when:
+
+* `UnityAccessEvaluator` is [created](UnityAccessEvaluator.md#authorizeAllHandle)
+
+### Authorize Any Privileges { #authorizeAny }
+
+``` java
+boolean authorizeAny(
+  UUID principal,
+  UUID resource,
+  Privileges... actions)
+```
+
+See:
+
+* [JCasbinAuthorizer](JCasbinAuthorizer.md#authorizeAny)
+
+Used when:
+
+* `UnityAccessEvaluator` is [created](UnityAccessEvaluator.md#authorizeAnyHandle)
+
 ### Grant Authorization { #grantAuthorization }
 
 ```java