Authorization

After a request is authenticated, the auth-gateway authorizes the principal against the matched route's requirements and any global rules. Authorization runs only when there is a matched route's auth context; if the route has no auth-related fields, the principal proceeds with no additional checks beyond authentication.

A denial returns 403 forbidden with the reason and the principal's roles and scopes in the JSON body.

Evaluation order01

The AuthzEvaluator runs these steps in sequence and returns deny on the first failure:

1. Required roles (require_roles) — if non-empty, the principal must have at least one of the listed roles (any-of). Otherwise: deny.

2. Required scopes (require_scopes) — if non-empty, the principal must have all of the listed scopes (all-of). Otherwise: deny.

3. Route Rhai rule (authz_rule) — if set, the expression is evaluated; if it denies, the request is denied. (A rule that allows does not short-circuit — evaluation continues to global rules.)

4. Global rules (auth.authz.global_rules) — each rule is evaluated in order and may deny.

If all steps pass, the request is allowed.

Roles and scopes02

These come from the principal that the provider produced:

• JWT / OIDC — roles from the roles claim, scopes from the whitespace-split scope claim.

• API key — roles are always ["api_consumer"]; scopes are the matched key entry's scopes.

• Forward auth — roles and scopes from the auth service's X-Auth-Role / X-Auth-Scopes.

• mTLS — roles from cn_to_roles; no scopes.

Set them per route:

routes:
  - path: /admin/*
    upstream: backend
    require_roles: ["admin", "superadmin"]   # any-of
    require_scopes: ["write"]                # all-of

Rhai rules03

A Rhai expression evaluates to a boolean: true means allow, false means deny. If evaluation errors (syntax, runtime, or a non-boolean result), the rule is treated as deny. The engine is sandboxed with limits — max expression depth 25/10, max 10,000 operations, and max string size 4096 bytes — so a runaway script is denied rather than hanging the request.

Rules run with these variables and helper functions in scope:

• principal — a map with id, name, roles (array), scopes (array), and attributes (map).

• request — a map with method and path.

• has_role(role) — true if the principal has role.

• has_scope(scope) — true if the principal has scope.

• has_any_role(roles) — true if the principal has any role in the array.

• has_all_roles(roles) — true if the principal has every role in the array.

routes:
  - path: /reports/*
    upstream: analytics
    # Allow admins, or anyone with the reports scope doing a GET.
    authz_rule: 'has_role("admin") || (has_scope("reports") && request.method == "GET")'

Global rules and the engine04

auth.authz configures the authorization engine and a list of global rules applied to every authenticated request after the per-route checks.

A global rule

How action combines with a rule's boolean outcome:

In other words: with action: allow, the rule expresses a condition that must hold (a false result denies); with action: deny, the rule expresses a forbidden condition (a true/deny result denies). Any rule can short-circuit to a denial; rules never override an earlier denial.

OPA05

When engine is opa (or both) and an opa block is configured, global rules are decided by an external Open Policy Agent server. The gateway POSTs an input document to the configured endpoint and reads a boolean result: true allows, anything else (or a missing result) denies.

The input.input document sent to OPA contains:

• principal — id, name, roles, scopes, attributes.

• request — method, path, and the request headers.

• route — upstream, path, and route metadata.

auth:
  default_provider: primary-jwt
  global_enforce: true
  authz:
    engine: both
    global_rules:
      # Rhai: block a path outright (deny when the expression is true)
      - name: block-internal
        engine: rhai
        rule: 'request.path == "/internal"'
        action: deny
      # OPA: defer the decision to a policy server
      - name: opa-policy
        engine: opa
        rule: "data.octopus.allow"
        action: allow
    opa:
      endpoint: http://opa:8181/v1/data/octopus/allow
      timeout: 100ms
      cache_ttl: 30s
      fail_open: false

See also06

• Authentication — producing the principal that gets authorized.

• Configuration reference.