Skip to main content

Authority Integration & Token Mediation

Summary​

The Access Gateway does not make authorization decisions on its own. It delegates to downstream authorities: Keycloak for token validation and exchange, and the Keymate Authorization Decision Provider for fine-grained permission evaluation. The gateway orchestrates these interactions and caches results to minimize latency.

Why It Exists​

Authorization at the gateway layer requires three distinct capabilities that the gateway itself does not own:

  • Token validation: Only the token issuer (Keycloak) can authoritatively determine whether a token is active.
  • Token exchange: When a frontend client's token must be scoped to a backend audience, an RFC 8693 exchange through Keycloak is required.
  • Permission evaluation: Fine-grained resource and scope checks are evaluated by the Keymate Authorization Decision Provider.

Where It Fits in Keymate​

Boundaries​

What this integration covers:

  • Token validation via Keycloak
  • OAuth 2.0 RFC 8693 token exchange
  • Permission evaluation via the Keymate Authorization Decision Provider
  • DPoP sender-constrained token support (RFC 9449)
  • Caching of exchanged tokens and permission decisions

What this integration does not cover:

How It Works​

Token Validation​

The gateway validates the access token through Keycloak's introspection endpoint to confirm the token is active and to identify the user. If the token is inactive or expired, the request is rejected with TOKEN_INACTIVE.

DPoP Support​

Access Gateway supports DPoP sender-constrained tokens (RFC 9449). When a request includes a DPoP proof, the gateway validates the cryptographic binding between the proof and the access token — preventing token theft and replay attacks. After validation, downstream services receive a standard Bearer token; DPoP terminates at the gateway.

Token Exchange​

When an access rule requires it, the gateway exchanges the caller's token for a token scoped to the target audience via Keycloak (RFC 8693). Exchanged tokens are cached to avoid repeated exchanges for the same user and client pair. If the exchange fails, the request is rejected with TOKEN_EXCHANGE_FAILED.

Permission Evaluation​

After token mediation, the gateway sends the token and resolved resources to the Keymate Authorization Decision Provider for evaluation. The decision determines the gateway's response:

DecisionAccess Gateway ResponseCached?
GRANT200 OKYes
DENY403 ForbiddenNo — permission changes take effect immediately
Error500 Internal Server ErrorNo

Example Scenario​

Scenario​

A frontend SPA (demo-spa) checks permissions on employee-data:can-view. An access rule triggers a token exchange to demo-api.

Input​

  • Actor: User with a valid access token (Bearer or DPoP) issued for demo-spa
  • Resource: employee-data with scope can-view
  • Action: Permission check
  • Context: Keymate-Client-Id: demo-spa

Expected Outcome​

Common Misunderstandings​

  • "Token exchange happens on every request." — Exchanged tokens are cached. Subsequent requests for the same user and client pair reuse the cached token.
  • "DPoP tokens are forwarded to downstream services." — DPoP terminates at the gateway. All downstream components receive Bearer tokens.
  • "A 403 response always means permission denied." — A 403 can also indicate a token exchange failure. Check the error code to distinguish RESOURCE_DENIED from TOKEN_EXCHANGE_FAILED.

Design Notes / Best Practices​

  • Authority call latency is reflected in the Keymate-Decision-Authority-Latency response header, helping distinguish gateway latency from downstream issues.
  • All authority calls are instrumented with OpenTelemetry for end-to-end tracing.
tip

Monitor the Keymate-Decision-Authority-Latency header. A sudden increase typically indicates downstream authority latency, not an Access Gateway problem.

Enforcement Pipeline

Request processing pipeline where authority integration occurs.

Decision Cache

How permission decisions and exchanged tokens are cached.

Runtime Evaluation Model

Access rules that determine when token exchange is needed.

Keymate Authorization Decision Provider

Fine-grained permission evaluation engine used by Access Gateway.