Authorization Middlewares

• acl — consumer/group-based allow-deny lists
• opa-authz — policy-as-code via an external Open Policy Agent server
• cel — inline CEL expressions; also the engine behind policy-driven routing (see below)

acl

Enforces access control based on consumer identity and group membership. Reads the standard x-auth-consumer and x-auth-consumer-groups headers set by upstream auth plugins.

x-barbacane-middlewares:
  - name: basic-auth
    config:
      realm: "my-api"
      credentials:
        - username: admin
          password: "env://ADMIN_PASSWORD"
          roles: ["admin", "editor"]
        - username: viewer
          password: "env://VIEWER_PASSWORD"
          roles: ["viewer"]
  - name: acl
    config:
      allow:
        - admin
      deny:
        - banned

Configuration

Evaluation order

1. Missing/empty x-auth-consumer header → 403
2. deny_consumers match → 403
3. allow_consumers match → 200 (bypasses group checks)
4. Resolve groups (merge x-auth-consumer-groups header + static consumer_groups config)
5. deny group match → 403 (takes precedence over allow)
6. allow non-empty + group match → 200
7. allow non-empty + no group match → 403
8. allow empty → 200 (only deny rules active)

Static consumer groups

You can supplement the groups from the auth plugin with static mappings:

- name: acl
  config:
    allow:
      - premium
    consumer_groups:
      free_user:
        - premium    # Grant premium access to specific consumers

Groups from the consumer_groups config are merged with the x-auth-consumer-groups header (deduplicated).

Error response

Returns 403 Forbidden with Problem JSON (RFC 9457):

{
  "type": "urn:barbacane:error:acl-denied",
  "title": "Forbidden",
  "status": 403,
  "detail": "Access denied by ACL policy",
  "consumer": "alice"
}

Set hide_consumer_in_errors: true to omit the consumer field.

opa-authz

Policy-based access control via Open Policy Agent. Sends request context to an OPA REST API endpoint and enforces the boolean decision. Typically placed after an authentication middleware so that auth claims are available as OPA input.

x-barbacane-middlewares:
  - name: jwt-auth
    config:
      issuer: "https://auth.example.com"
      skip_signature_validation: true
  - name: opa-authz
    config:
      opa_url: "http://opa:8181/v1/data/authz/allow"

Configuration

OPA input payload

The plugin POSTs the following JSON to your OPA endpoint:

{
  "input": {
    "method": "GET",
    "path": "/admin/users",
    "query": "page=1",
    "headers": { "x-auth-consumer": "alice" },
    "client_ip": "10.0.0.1",
    "claims": { "sub": "alice", "roles": ["admin"] },
    "body": "..."
  }
}

• claims is included only when include_claims is true and the x-auth-claims header contains valid JSON (set by auth plugins like jwt-auth, oauth2-auth)
• body is included only when include_body is true

Decision logic

The plugin expects OPA to return the standard Data API response:

{ "result": true }

Error responses

403 Forbidden — OPA denies access:

{
  "type": "urn:barbacane:error:opa-denied",
  "title": "Forbidden",
  "status": 403,
  "detail": "Authorization denied by policy"
}

503 Service Unavailable — OPA is unreachable or returns a non-200 status:

{
  "type": "urn:barbacane:error:opa-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "OPA service unreachable"
}

Example OPA policy

package authz

default allow := false

# Allow admins everywhere
allow if {
    input.claims.roles[_] == "admin"
}

# Allow GET on public paths
allow if {
    input.method == "GET"
    startswith(input.path, "/public/")
}

cel

Inline policy evaluation using CEL (Common Expression Language). Evaluates expressions directly in-process — no external service needed. CEL is the same language used by Envoy, Kubernetes, and Firebase for policy rules.

Two modes:

• Access-control mode (default, no on_match): true → continue, false → 403.
• on_match mode (on_match present): on true, take the configured actions — write context keys (set_context) and/or reject with a configured status + code (deny). On false, continue unchanged (no 403). Used to drive policy-driven routing and per-tier resource gating (e.g. block gpt-4* for the free tier without standing up a separate target — see example).

x-barbacane-middlewares:
  - name: jwt-auth
    config:
      issuer: "https://auth.example.com"
  - name: cel
    config:
      expression: >
        'admin' in request.claims.roles
        || (request.method == 'GET' && request.path.startsWith('/public/'))

Configuration

on_match.set_context

on_match.deny

Request context

The expression has access to a request object with these fields:

CEL features

CEL supports a rich expression language:

// String operations
request.path.startsWith('/api/')
request.path.endsWith('.json')
request.headers.host.contains('example')

// List operations
'admin' in request.claims.roles
request.claims.roles.exists(r, r == 'editor')

// Field presence
has(request.claims.email)

// Logical operators
request.method == 'GET' && request.consumer != ''
request.method in ['GET', 'HEAD', 'OPTIONS']
!(request.client_ip.startsWith('192.168.'))

Decision logic

Error responses

403 Forbidden — access-control mode, expression evaluates to false:

{
  "type": "urn:barbacane:error:cel-denied",
  "title": "Forbidden",
  "status": 403,
  "detail": "Access denied by policy"
}

500 Internal Server Error — invalid expression or non-boolean result:

{
  "type": "urn:barbacane:error:cel-evaluation",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "expression returned string, expected bool"
}

Configured 4xx — on_match.deny fires:

{
  "type": "urn:barbacane:error:model_not_permitted",
  "title": "Forbidden",
  "status": 403,
  "code": "model_not_permitted",
  "detail": "gpt-4* is restricted to the premium tier"
}

The URN type, response code, and (optionally) title are derived from on_match.deny.code + status; detail is the configured message or, if absent, the code itself.

Match-and-deny: per-tier model gating

The on_match.deny action turns cel into a fully programmable gate — useful when access depends on a combination of caller attributes and request body that the dispatcher’s static allow/deny lists can’t express. The canonical case is “block expensive models for the free tier”:

x-barbacane-middlewares:
  - name: jwt-auth
    config:
      issuer: "https://auth.example.com"
  - name: cel
    config:
      expression: >
        request.body_json.model.startsWith('gpt-4')
        && request.claims.tier != 'premium'
      on_match:
        deny:
          status: 403
          code: model_not_permitted_for_tier
          message: "gpt-4* is restricted to the premium tier"

The expression sees both the parsed JSON body and the JWT claims, so a single rule covers what would otherwise need two layers (a custom auth filter plus a separate routing config). Pair with ai-proxy’s routes for static catalog policy and reach for cel only when the rule depends on caller context.

Policy-driven routing (cel stacking)

CEL in routing mode is the building block for declarative policy routing. Stack one entry per rule — each writes a distinct set of context keys. Downstream plugins (notably ai-proxy via ai.target, and all AI Gateway middlewares via ai.policy) read the written keys to pick their active behavior.

x-barbacane-middlewares:
  - name: cel
    config:
      expression: "request.claims.tier == 'premium'"
      on_match:
        set_context:
          ai.policy: premium
          ai.target: premium

  - name: cel
    config:
      expression: "'ai:premium' in request.claims.scopes"
      on_match:
        set_context:
          ai.policy: premium
          ai.target: premium

  - name: cel
    config:
      expression: "request.headers['x-ai-model-tier'] == 'best'"
      on_match:
        set_context:
          ai.policy: premium
          ai.target: premium

Each entry is evaluated in order. On a true match, the context keys are written (the last match wins when keys collide); on false, the entry is a no-op. No request is ever denied by a routing-mode cel — it’s pure data-plane policy, not access control.

See ADR-0024 §Policy-Driven Model Routing for the full design.

cel vs OPA