Skip to main content

Understanding AuthZEN Authorization

Early Access

AuthZEN support is currently in early access, available starting v3.21.0-ea.3.

AuthZEN is an open standard for asking a separate authorization system, called a Policy Decision Point (PDP), whether a specific request should be allowed. Instead of deciding on its own, Traefik Hub sends the relevant details of a request, such as the caller's identity and what it's trying to do, to a PDP you run, for example OpenFGA or Keycloak. Traefik Hub waits for the PDP's decision and enforces it: it never authors or stores policy itself.

Token exchange delegates authority to the caller before AuthZEN evaluates the request. Transparency Logs then records the decision AuthZEN makes.

Why hand the decision to another system​

Traefik Hub already verifies who is calling (JSON Web Tokens, OAuth, OIDC) and can substitute claims from a verified token into inline rules. That covers most everyday API traffic.

AI agents raise a different problem. An agent calls tools, hands work to other agents, and can run unattended for hours. A single inline rule cannot express every business condition an organization wants to check before an agent acts. For example, a specific transfer amount, requested by a specific agent on behalf of a specific user, must fall within a policy that a compliance team defines. That policy can change independently of the gateway.

AuthZEN closes this gap by defining a standard way to ask an external decision-maker. Traefik Hub packages the relevant details from the request and forwards them to the PDP. The PDP replies allow or deny.

The two roles: PEP and PDP​

AuthZEN separates two roles that AuthZEN itself calls the PEP and the PDP:

  • The Policy Enforcement Point (PEP) intercepts the request and enforces whatever the PDP decides. Traefik Hub is a PEP.
  • The Policy Decision Point (PDP) holds the actual authorization logic and returns a decision. Traefik Hub does not include a PDP; connect an existing AuthZEN-compliant PDP, such as OpenFGA or Keycloak, to a route to use this feature.

Traefik Hub never authors or stores policy. It converts each request into the shape AuthZEN expects, sends it to the PDP you configure, and enforces the response.

How Traefik Hub builds an AuthZEN request​

An AuthZEN decision request has four parts:

  • Subject: who or what is making the request, for example the caller's identity from a verified token.
  • Action: what the caller wants to do, for example an HTTP method or an MCP tool name.
  • Resource: what the action targets, for example a specific account or file.
  • Context: any other detail the PDP's policy needs, for example a transaction amount or an agent identifier.

Traefik Hub fills in these four parts using a COAZ mapping: a small configuration block that tells the gateway where to find each value. A mapping field is either a literal value, or, when prefixed with $, a CEL expression evaluated against the request. For example, $token.sub reads the sub claim from the caller's verified token, and $request.headers['X-Resource'] reads a request header.

A mapping produces either a single decision (an evaluation) or several decisions in one call (evaluations), matching the two request shapes the AuthZEN specification defines.

Where AuthZEN fits in Traefik Hub​

Traefik Hub applies AuthZEN as a middleware, so it fits into the same routing model as any other middleware: attach it to a route, and every matching request goes through it before reaching your service.

Two gateways can use AuthZEN, because the value each one reads and enforces differs:

  • API Gateway evaluates one COAZ mapping against each incoming HTTP request.
  • MCP Gateway matches each MCP request against a list of policies, one per MCP method or tool, and evaluates the mapping for whichever policy matches first. Most MCP methods already have a default mapping built in, so you only need to write a policy for the tools specific to your own MCP servers. initialize is the exception: the binding defines no mapping for it and it is not in the pass-through set, so a route with only the built-in defaults denies it and no client can complete a handshake. Write a policy for initialize. Use strategy: bypass if you don't want the PDP involved in this method at all, so the request goes through without an allow/deny check. See the AuthZEN specification's default mappings for exactly what each one sends to the PDP.

Both gateways refuse the request whenever the PDP denies it, whenever no policy matches, or whenever the PDP can't be reached. Traefik Hub fails closed by default rather than letting an unverifiable request through.

A PDP denial returns the response you configured in onDenyResponse. If the PDP is unreachable, returns an error of its own, or sends back a response Traefik Hub can't parse, Traefik Hub skips onDenyResponse instead. It returns a plain 500 Internal Server Error, since it has no decision to enforce.

Next steps​