​Aserto Authorization Policy

This policy will authorize requests using Aserto. If the request is not authorized, a 403 response will be returned.

This policy is designed to be highly customizable in order to tailor the authorization requests to the specific needs of your application. You can use the default authorization context, or you can programmatically add attributes to the request using the setAuthorizationContext method.

Using this policy in conjunction with an authorization policy will automatically set the identity_context for the user in the request.

​Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

{
  "name": "my-aserto-authz-inbound-policy",
  "policyType": "aserto-authz-inbound",
  "handler": {
    "export": "AsertoAuthZInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "authorizerApiKey": "f1381f61.......f3dw31",
      "policyName": "api-auth",
      "tenantId": "070e5e6d-f71d-4419-aa8f-4a99207bce2b"
    }
  }
}

​Policy Configuration

• name <string> - The name of your policy instance. This is used as a reference in your routes.
• policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be aserto-authz-inbound.
• handler.export <string> - The name of the exported type. Value should be AsertoAuthZInboundPolicy.
• handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
• handler.options <object> - The options for this policy. See Policy Options below.

​Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

• allowUnauthorizedRequests <boolean> - Indicates whether the request should continue if authorization fails. Default is false which means unauthorized users will automatically receive a 403 response. Defaults to false.
• tenantId (required) <string> - The Aserto Tenant ID.
• authorizerApiKey (required) <string> - The Aserto API key.
• authorizerApiUrl <string> - The Aserto Authorizer API URL. Defaults to "https://authorizer.prod.aserto.com".
• policyName <string> - The policy instance name. Defaults to "api-auth".
• serviceName (required) <string> - Canonicalized service name.
• userSubPropertyPath <string> - The path to the user's sub property in the request. Defaults to ".sub".

​Using the Policy

​Authorization Attributes

There are two options for authorization attributes in the Aserto Policy. You can use the default attributes or you can programmatically add attributes to the request using the setAuthorizationContext method.

​Default Attributes

If you don't set any attributes, the policy will automatically use the following authorization context.

The identity_context will be set to the user's sub. The user property value can be customized by setting the userSubPropertyPath option. For example, if you want to get the user's email address and you have set an email property on the API Key Metadata, you can set the value to .data.email. Similarly, you can select values on JWT tokens by setting the value to .data.claim.

The resource_context will be set to the object_type and relation properties as shown in the example below. The object_id will be set to a concatenation of the service name, request method, and route path.

The policy_context will be set to the decisions and path properties as shown in the example below.

The policy_instance will be set to the authorizerPolicyName property set in the policies options.

{
  "identity_context": {
    "type": "IDENTITY_TYPE_SUB",
    "identity": "user-sub-id"
  },
  "resource_context": {
    "object_type": "endpoint",
    "object_id": "SERVICE_NAME:REQUEST_METHOD:ROUTE_PATH",
    "relation": "can_invoke"
  },
  "policy_context": {
    "decisions": ["allowed"],
    "path": "rebac.check"
  },
  "policy_instance": {
    "name": "AUTHORIZATION_POLICY_NAME",
    "instance_label": "AUTHORIZATION_POLICY_NAME"
  }
}

​Programmatically Setting Attributes

For the more robust customization of the authorization request, you can set authorization context programmatically. This is done by running a custom inbound policy before the authorization policy. The custom policy can set any attribute on the authorization request.

Below is an example of how you could set the resource_context.id attribute to the value of the id route parameter.

import {
  ZuploContext,
  ZuploRequest,
  AsertoAuthZInboundPolicy,
} from "@zuplo/runtime";

export default async function policy(
  request: ZuploRequest,
  context: ZuploContext,
  options: MyPolicyOptionsType,
  policyName: string,
) {
  // Set the custom context
  AsertoAuthZInboundPolicy.setAuthorizationContext(context, {
    resource_context: {
      id: request.params.id,
      type: "resource",
    },
    policy_instance: {
      name: "todo",
      instance_label: "todo",
    },
    policy_context: {
      decisions: ["allowed"],
      path: "todoApp.GET.todos",
    },
  });

  return request;
}

Read more about how policies work