​AuthZEN Authorization Policy

This policy will authorize requests using a PDP (Policy Decision Point) service that is compatible with the AuthZen standard. Read more about the AuthZen working group.

It is designed to be extremely simple to configure, with a default configuration that can dynamically read the subject, resource and action id from the Zuplo request or context objects using the special $authzen-prop(request.headers.user-id) syntax.

Example options:

{
  "authorizerHostname": "example.aserto.com",
  "subject": {
    "type": "identity",
    "id": "$authzen-prop(request.user.sub)"
  },
  "resource": {
    "type": "route",
    "id": "$authzen-prop(context.route.path)"
  },
  "action": {
    "name": "$authzen-prop(request.method)"
  },
  "throwOnError": true // defaults to true if not specified
}

Note, the $authzen-prop syntax only works on this policy and on the id and name properties.

​Configuration

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

{
  "name": "my-authzen-inbound-policy",
  "policyType": "authzen-inbound",
  "handler": {
    "export": "AuthZenInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "action": {
        "name": "$authzen-prop(request.method)"
      },
      "authorizerAuthorizationHeader": "Bearer $env(AUTHZEN_PDP_TOKEN)",
      "authorizerHostname": "example.aserto.com",
      "resource": {
        "id": "$authzen-prop(context.route.path)",
        "type": "route"
      },
      "subject": {
        "id": "$authzen-prop(request.user.sub)",
        "type": "identity"
      },
      "throwOnError": true
    }
  }
}

​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 authzen-inbound.
• handler.export <string> - The name of the exported type. Value should be AuthZenInboundPolicy.
• 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.

• authorizerHostname (required) <string> - The hostname of the AuthZen PDP service.
• authorizerAuthorizationHeader <string> - The authorization header to use when communicating with the AuthZen PDP service.
• subject (required) <object> - The subject of the request.
  • type (required) <string> - The type of the resource.
  • id (required) <string> - The id of the resource. Note you can use the $authzen-prop() syntax to reference the resource id.
• resource (required) <object> - The resource of the request. Note you can use the $authzen-prop() syntax to reference the resource id.
  • type (required) <string> - The type of the resource.
  • id (required) <string> - The id of the resource. Note you can use the $authzen-prop() syntax to reference the resource id.
• action (required) <object> - The action of the request. Note you can use the $authzen-prop() syntax to reference the action.
  • name (required) <string> - The name of the action. Note you can use the $authzen-prop() syntax to reference the action name.
• throwOnError <boolean> - If explicitly set to false, the policy will not throw an error if there is any problem communicating with the AuthZen PDP service and allow calls through. By default throwOnError is assumed to be on/true. Defaults to true.

​Using the Policy

By default, the policy will use the subject, resource, and action properties from the policy options file, with the special $authzen-prop() syntax to reference dynamic values.

However, you can also have programmatic control over the payload sent to the PDP by setting the payload wholly or partially using the setAuthorizationContext method in a custom policy before the AuthZenInboundPolicy.

AuthZenInboundPolicy.setAuthorizationPayload(context, {
  subject: {
    type: "user",
    id: request.user.data.organization,
  },
  resource: {
    type: "pizza",
    id: ContextData.get(context, "pizza-size"),
  },
  action: { name: request.method },
});

This object will be combined with the one generated by the options with this authorization payload set on context taking priority.

Read more about how policies work