Skip to main content

Runtime Evaluation Model

Summary​

The Access Gateway uses access rules to determine how each permission check request should be processed. Access rules are declarative definitions that map incoming requests to two key outcomes: whether a token exchange is required, and what resources should be checked. This allows the gateway to route authorization requests correctly without hardcoding client relationships or resource mappings.

Why It Exists​

Different client applications have different authorization relationships. A frontend SPA calling a backend API requires a token exchange to obtain audience-scoped permissions. An API Gateway plugin may need the gateway to resolve which resource an endpoint maps to. Without access rules:

  • Token exchange decisions would need to be hardcoded per client pair.
  • Resource resolution would require each enforcer to know the exact resource names.
  • Changes in routing logic would require code deployments.

Access rules externalize this logic into a declarative, configurable model.

Where It Fits in Keymate​

Access rules are evaluated within the enforcement pipeline, after token validation and before the authorization decision. The rule evaluation result determines whether token exchange is needed and what resources to check with the Keymate Authorization Decision Provider.

Boundaries​

What access rules cover:

  • Determining whether token exchange is needed for a given client relationship
  • Resolving resources when the caller does not provide them explicitly (see Resource Resolution)

What access rules do not cover:

How It Works​

Access rules provide the gateway with two capabilities:

Token Exchange​

When a caller (e.g., a frontend SPA) needs to check permissions on a resource that belongs to a different audience (e.g., a backend API), the access rule instructs the gateway to exchange the caller's token for one scoped to the target audience via Keycloak (RFC 8693). The exchanged token is then used for the permission check.

Resource Resolution​

When a caller knows the target URI and HTTP method but not the specific resource name, the access rule maps the request to the correct resource. This is the typical pattern for API Gateway plugins and service mesh integrations. See Resource Resolution & Routing Metadata for details.

These two capabilities are independent and composable — a single rule can trigger both token exchange and resource resolution.

Example Scenario​

Scenario​

A frontend SPA (demo-spa) sends a permission check for employee-data:can-view. An access rule determines that a token exchange to demo-api is required before checking permissions.

Input​

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

Expected Outcome​

  • Decision: GRANT
  • Why: The access rule matches the demo-spa → demo-api client relationship, triggers a token exchange, and the Keymate Authorization Decision Provider grants access on the exchanged token

Common Misunderstandings​

  • "Access rules evaluate permissions." — No. Access rules determine how a request should be routed (token exchange, resource resolution). The actual permission evaluation is delegated to the Keymate Authorization Decision Provider.
  • "Resource resolution and token exchange are mutually exclusive." — No. A single rule can trigger both when needed.

Design Notes / Best Practices​

  • Use token exchange rules for cross-client authorization scenarios (e.g., frontend SPA checking permissions on a backend API).
  • Use resource resolution for gateway plugin and service mesh integrations where the caller knows the URI and method but not the resource name.
tip

For application-level calls (SDKs, Admin Console), provide resources explicitly in the request body. Reserve resource resolution for gateway plugin and service mesh integrations where the caller delegates resource mapping to the gateway.

Resource Resolution

URI-driven resource resolution for gateway plugin integrations.

Enforcement Pipeline

Request processing pipeline where access rules are evaluated.

Authority Integration

Token exchange and permission evaluation flow.

Keymate Authorization Decision Provider

Fine-grained permission evaluation engine used by Access Gateway.