UnityAccessDecorator¶

UnityAccessDecorator is used by UnityCatalogServer to enforce access control rules on the following API services endpoints:

• /api/2.1/unity-catalog/
• /api/1.0/unity-control/ (except /api/1.0/unity-control/auth/tokens)

UnityAccessDecorator is used only when UnityCatalogServer runs with Server Authorization enabled.

UnityAccessDecorator uses AuthorizeExpression.

UnityAccessDecorator is a DecoratingHttpServiceFunction (Armeria).

Creating Instance¶

UnityAccessDecorator takes the following to be created:

• UnityCatalogAuthorizer

While being created, UnityAccessDecorator creates the UnityAccessEvaluator (with the UnityCatalogAuthorizer).

UnityAccessDecorator is created when:

• UnityCatalogServer is requested to add the API services (with Server Authorization enabled)

UnityAccessEvaluator¶

UnityAccessDecorator creates an UnityAccessEvaluator (with the UnityCatalogAuthorizer) when created.

This UnityAccessEvaluator is used to evaluate a principal to access securables while checking authorization.

Serve Incoming HTTP Request¶

HttpResponse serve(
  HttpService delegate,
  ServiceRequestContext ctx,
  HttpRequest req)

serve prints out the following DEBUG message to the logs:

AccessDecorator checking [path]

serve finds the service method.

When found, serve finds the @AuthorizeExpression and the @AuthorizeKey annotations (if defined on the method and the parameters).

Only when there are an authorize expression and keys found, serve finds the principal and authorizeByRequest.

Otherwise, serve prints out one of the WARN messages to the logs and passes the request on to the target (delegate) service (as if no authorization were even attempted).

No authorization resource(s) found.

No authorization expression found.

Couldn't unwrap service.

Find Service Method¶

Method findServiceMethod(
  HttpService httpService)

findServiceMethod tries to unwrap the given HttpService to be a SimpleDecoratingHttpService that is in turn tried to be unwrapped to an AnnotatedService.

If the given HttpService is unwrapped to an AnnotatedService successfully, findServiceMethod prints out the following DEBUG message to the logs:

serviceName = [serviceName], methodName = [methodName]

findServiceMethod gives the Class by the serviceName and then finds the methods in the Class matching the methodName.

findServiceMethod returns the one and only methodName method of the Class, if found. Otherwise, it's undefined (null).

Find Authorize Keys¶

List<KeyLocator> findAuthorizeKeys(
  Method method)

findAuthorizeKeys finds @AuthorizeKey annotations on the given Method (Java). If found, findAuthorizeKeys adds a locator with the following:

findAuthorizeKeys finds @AuthorizeKey annotations (incl. @AuthorizeKeys) on the method's parameters.

Both AuthorizeKey and AuthorizeKeys present

findAuthorizeKeys collects the AuthorizeKeys.

For keys with the key specified, findAuthorizeKeys adds a locator with the following:

Otherwise, findAuthorizeKeys finds parameters with @Param annotation. If found, findAuthorizeKeys adds a locator with the following:

Couldn't find param key for authorization key

Find Authorize Expression¶

String findAuthorizeExpression(
  Method method)

findAuthorizeExpression takes the AuthorizeExpression of the given method.

When found, findAuthorizeExpression prints out the following DEBUG message to the logs and returns the authorize expression value:

authorize expression = [annotation_value]

Otherwise, findAuthorizeExpression prints out the following DEBUG message to the logs and returns no authorize expression value (null):

authorize = (none found)

Authorize By Request¶

HttpResponse authorizeByRequest(
  HttpService delegate,
  ServiceRequestContext ctx,
  HttpRequest req,
  UUID principal,
  List<KeyLocator> locators,
  String expression)

authorizeByRequest...FIXME

Check Authorization¶

void checkAuthorization(
  UUID principal,
  String expression,
  Map<SecurableType, Object> resourceKeys)

In essence, checkAuthorization reports a BaseException to indicate "Access denied". Otherwise, authorization is granted.

checkAuthorization prints out the following DEBUG message to the logs:

resourceKeys = [resourceKeys]

checkAuthorization resolves resource names into IDs.

checkAuthorization prints out the following DEBUG message to the logs:

resourceIds = [resourceIds]

checkAuthorization requests the UnityAccessEvaluator to 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:

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:

logger.UnityAccessDecorator.name = io.unitycatalog.server.auth.decorator.UnityAccessDecorator
logger.UnityAccessDecorator.level = all

Refer to Logging.