Authorization

#Axiomatics Authorization Policy

This policy will authorize requests using Axiomatics Policy Server. 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 add default attributes on the policy that are included in every request, or you can programmatically add attributes to the request using the setAuthAttributes method.

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

Beta

This policy is in beta. You can use it today, but it may change in non-backward compatible ways before the final release.

#Configuration

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

{
  "name": "my-axiomatics-authz-inbound-policy",
  "policyType": "axiomatics-authz-inbound",
  "handler": {
    "export": "AxiomaticsAuthZInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "pdpPassword": "$env(PDP_PASSWORD)",
      "pdpUrl": "https://pdp.example.com",
      "pdpUsername": "pdp-user"
    }
  }
}

json

#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 axiomatics-authz-inbound.
handler.export <string> - The name of the exported type. Value should be AxiomaticsAuthZInboundPolicy.
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.
pdpUrl (required) <string> - The URL to which the plugin will make a JSON POST request before proxying the original request.
pdpUsername (required) <string> - The username to use when authenticating with the PDP.
pdpPassword (required) <string> - The password to use when authenticating with the PDP.
includeDefaultActionAttributes <boolean> - Indicates whether the plugin should include default action attributes in the authorization request. Defaults to true.
includeDefaultResourceAttributes <boolean> - Indicates whether the plugin should include default resource attributes in the authorization request. Defaults to true.
includeDefaultSubjectAttributes <boolean> - Indicates whether the plugin should include default subject attributes in the authorization request. Defaults to true.
tokenHeaderName <string> - The name of the header that carries the JWT. Defaults to "Authorization".
accessSubjectAttributes <object[]> - A list of attributes that will be included in the authorization request.
- attributeId (required) <string> - The attribute ID that will be used in the PDP request.
- value (required) <string> - The value of the attribute.
resourceAttributes <object[]> - A list of attributes that will be included in the authorization request.
- attributeId (required) <string> - The attribute ID that will be used in the PDP request.
- value (required) <string> - The value of the attribute.
actionAttributes <object[]> - A list of attributes that will be included in the authorization request.
- attributeId (required) <string> - The attribute ID that will be used in the PDP request.
- value (required) <string> - The value of the attribute.

#Using the Policy

#Authorization Attributes

There are a few different ways authorization attributes are set on the authorization request.

#Default Attributes

By default the policy will set the following attributes on the authorization request:

request.user.sub - (AccessSubject) The subject of the user making the request. Only set if the user is authenticated.
request.method - (Action) The HTTP method of the request.
request.scheme - (Resource) The scheme of the request URL.
request.host - (Resource) The host of the request URL.
request.pathname - (Resource) The pathname of the request URL.
request.query.* - (Resource) The value of each query parameter in the request URL. For example ?foo=baz would set request.query.foo=baz.
request.params.* - (Resource) The value of each path parameter in the request URL. For example the route pattern /accounts/:id would set request.params.accounts=value.

The default attributes can be disabled by setting the policy options that start with includeDefault to false, for example includeDefaultResourceAttributes: false will disable the Resource category attributes.

Below is an example of the default authorization request.

{
  "Request": {
    "AccessSubject": [
      {
        "Attribute": [
          {
            "AttributeId": "request.user.sub",
            "Value": "nate"
          }
        ]
      }
    ],
    "Action": [
      {
        "Attribute": [
          {
            "AttributeId": "request.method",
            "Value": "GET"
          }
        ]
      }
    ],
    "Resource": [
      {
        "Attribute": [
          {
            "AttributeId": "request.scheme",
            "Value": "https"
          },
          {
            "AttributeId": "request.host",
            "Value": "my-api-main-bdeec51.d2.zuplo.dev"
          },
          {
            "AttributeId": "request.pathname",
            "Value": "/test"
          },
          {
            "AttributeId": "request.params.id",
            "Value": "123"
          },
          {
            "AttributeId": "request.query.param",
            "Value": "1"
          }
        ]
      }
    ]
  }
}

json

#Hard Coded Attributes

In some cases it cane be useful to set hard coded attributes on the policy itself. On case for this might be to set the environment the API is running in so that different policies can be applied to say a staging or development environment.

An example of how you could set the custom.environment attribute to an environment variable is shown below.

"resourceAttributes": [
  {
    "attributeId": "custom.environment",
    "value": "$env(CUSTOM_ENVIRONMENT)"
  }
]

json

#Programmatically Setting Attributes

For the more robust customization of the authorization request, you can set authorization attributes 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 custom.resourceId attribute to the value of a property in the request body.

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

export default async function policy(
  request: ZuploRequest,
  context: ZuploContext,
  options: MyPolicyOptionsType,
  policyName: string,
) {
  // Get the body of the request
  const body = await request.json();

  // Set the custom attribute
  AxiomaticsAuthZInboundPolicy.setAuthAttributes(context, {
    Resource: [
      {
        Attribute: [
          {
            AttributeId: "custom.recordId",
            Value: body.recordId,
          },
        ],
      },
    ],
  });

  return request;
}