Enforcement Pipeline
Summary
Every permission check request that enters the Access Gateway passes through a structured enforcement pipeline. The pipeline validates the request, verifies the caller's identity, evaluates access rules, consults the decision cache, and — when needed — delegates the authorization decision to the Keymate Authorization Decision Provider. The result is a deterministic GRANT or DENY response.
Why It Exists
Permission checks from diverse sources — SDKs, API Gateway plugins, and platform components — require consistent, predictable processing. The enforcement pipeline provides a single ordered path through which every request passes, ensuring that validation is never skipped and caching never short-circuits security checks.
Where It Fits in Keymate
The enforcement pipeline is the core processing model of the Access Gateway. It governs the entire lifecycle of a permission check request, from the moment an enforcer call arrives to the final GRANT or DENY response.
Boundaries
What the pipeline covers:
- Validating requests and producing authorization decisions
- Returning structured error codes for rejected requests
What the pipeline does not cover:
- Policy definition or policy evaluation logic (handled by the Keymate Authorization Decision Provider)
- Token issuance or user authentication (handled by Keycloak)
How It Works
The pipeline validates the request, verifies the access token, evaluates access rules, and produces a decision:
- Validation — the gateway rejects requests with missing or invalid headers, expired tokens, or malformed bodies. Each failure produces a specific error code.
- Caching — valid requests are checked against the subject-based decision cache. A cache hit returns the previous decision immediately, without calling the authorization authority.
- Authorization decision — on a cache miss, the gateway performs token exchange if required by access rules, delegates the permission evaluation to the Keymate Authorization Decision Provider, and caches the result.
Response Headers
Every response includes structured metadata headers:
| Header | Value | Description |
|---|---|---|
Keops-Gateway | version="1.0.0" | Gateway identification |
Keops-Decision-Latency | Milliseconds (e.g., 50) | Total decision latency |
Keops-Decision | result="allow", authority="keycloak" | Decision result and authority source |
Keops-Decision-Cache | hit or miss | Whether the decision was served from cache |
Keops-Decision-Authority-Latency | Milliseconds (e.g., 13) | Authority call latency (only when authority was called) |
Error Codes
| Error Code | HTTP Status | Cause |
|---|---|---|
INVALID_ENFORCER | 400 | Missing or malformed Keops-Enforcer header. The gateway does not read the older Keymate-Enforcer name, so a request that sends only that name gets this error |
DPOP_PROOF_INVALID | 401 | Invalid DPoP proof JWT |
DPOP_REPLAY_DETECTED | 401 | DPoP proof jti already used |
DPOP_BINDING_MISMATCH | 401 | DPoP proof thumbprint does not match the token binding |
DPOP_DOWNGRADE_DETECTED | 401 | DPoP-bound token sent with Bearer scheme |
MISSING_BEARER_TOKEN | 401 | Missing Authorization header |
CLIENT ID MISSING | 400 | Missing Keops-Client-Id header on the logout or revoke endpoint. Only those two endpoints raise it; the permission check does not require the header |
BAD_REQUEST | 400 | Invalid request body structure |
TOKEN_INACTIVE | 401 | Token inactive or expired |
consumer-client-mismatch | 401 | Keops-Client-Id was sent but does not match the client the token belongs to. Returned as an application/problem+json response |
RESOURCE_RESOLUTION_FAILED | 400 | No matching resource resolution rule |
TOKEN_EXCHANGE_FAILED | 403 | Token exchange failed |
RESOURCE_DENIED | 403 | Permission denied by the authorization authority |
Example Scenario
Scenario
A Keymate Java SDK sends a permission check for employee-data:can-view on behalf of an authenticated user.
Input
- Actor: Authenticated user with a valid access token (Bearer or DPoP)
- Resource:
employee-datawith scopecan-view - Action: Permission check
- Context:
Keops-Client-Id: demo-spa
Expected Outcome
- Decision: GRANT
- Why: The request passes validation, the access rule triggers a token exchange, and the Keymate Authorization Decision Provider grants access. The result is cached for subsequent requests.
Common Misunderstandings
- "A cache hit skips validation." — No. The cache is consulted only after the request has been fully validated. A cached result only skips the authority call.
- "Every request calls the authorization authority." — No. The subject-based cache serves repeated checks for the same user and resource without an authority call.
Design Notes / Best Practices
- Each error code maps to a specific validation failure, making it straightforward to diagnose rejected requests.
- The
Keops-Decision-Authority-Latencyheader helps distinguish gateway latency from downstream authority latency.
When debugging a denied request, check the error code in the response first. It narrows the investigation scope immediately.
Related Docs
Overview
Access Gateway capabilities, endpoints, and system role.
Runtime Evaluation Model
Access Rule Engine that determines token exchange and resource resolution.
Decision Cache
Subject-based caching architecture.
Keymate Authorization Decision Provider
Fine-grained permission evaluation engine used by Access Gateway.