Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท Authorization Services

RPTs and Policy Enforcement

Request permissions from Keycloak with the UMA grant, read the RPT permissions claim, choose decision or permissions response modes, and enforce them in an API.

You have defined resources, scopes, policies, and permissions. Now an API must ask Keycloak "may this caller do this?" and obey the answer. This lesson covers the two protocol pieces involved, the requesting party token (RPT) and the policy enforcer, and shows how an API can enforce results by hand or by library.

Keycloak does not run on this site. HTTP calls are shown as read-only examples; the TryIts are stand-ins that build the requests and check RPT-style claims locally. No real tokens or secrets appear.

The UMA grant and the RPT

Keycloak implements permission requests as an OAuth 2.0 grant type from the User-Managed Access specification. The client sends its normal access token to the token endpoint and asks for permissions:

Terminal
curl -X POST "https://auth.example.com/realms/demo/protocol/openid-connect/token" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
  --data-urlencode "audience=invoice-api" \
  --data-urlencode "permission=invoice#edit" \
  --data-urlencode "permission=invoice#view"

Key parameters:

  • audience: the client ID of the resource server.
  • permission: resource, or resource#scope. It can repeat. Without it, Keycloak evaluates all permissions for the user ("what can this person do at all?").
  • response_mode: decision returns just {"result": true} (or HTTP 403 when denied); permissions returns a JSON list of grants instead of a token; omitted means a full RPT.
  • submit_request: ask the resource owner for access when denied (used with user-managed sharing).

If granted, the response contains a new access token: the RPT. Its payload looks like a normal access token plus an authorization claim:

JSON
{
  "exp": 1900000000,
  "aud": "invoice-api",
  "authorization": {
    "permissions": [
      { "rsid": "a1f2", "rsname": "invoice-42", "scopes": ["view", "edit"] }
    ]
  }
}

rsid is the resource ID, rsname its name, and scopes the granted actions. The API can read these claims, but must first validate the token signature, issuer, audience, and expiry.

sequenceDiagram
    participant C as Client
    participant A as Resource server API
    participant K as Keycloak
    C->>A: GET /invoices/42 (access token)
    A->>K: UMA ticket request (audience, permission)
    K->>K: Evaluate policies
    K-->>A: RPT or 403
    A-->>C: 200 data or 403

The API asks Keycloak per request, or caches the RPT for a short time.

Reading the permissions claim

Once the API holds an RPT, deciding is a lookup. Matching resource by name or ID, then checking the scope:

JS Stand-in: check scopes in an RPT payload

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The policy enforcer

Writing this per route gets repetitive. Keycloak offers a policy enforcer, a component of the adapter or framework integration (for example the Keycloak Java adapters and several community libraries) that:

  1. Matches the request path to a resource (using the resource's URIs, with patterns like /invoices/*).
  2. Maps the HTTP method to a scope if configured.
  3. Obtains an RPT (or a decision) from Keycloak and caches it.
  4. Allows the request or answers 403.

The enforcer is configured in JSON, downloadable from the client's Action > Download adapter config area under Authorization. Roughly:

JSON
{
  "realm": "demo",
  "auth-server-url": "https://auth.example.com",
  "resource": "invoice-api",
  "credentials": { "secret": "<client-secret>" },
  "policy-enforcer": {
    "enforcement-mode": "ENFORCING",
    "paths": [
      { "path": "/invoices/*", "methods": [
          { "method": "GET",  "scopes": ["view"] },
          { "method": "PUT",  "scopes": ["edit"] } ] },
      { "path": "/health", "enforcement-mode": "DISABLED" }
    ]
  }
}

Exact option names depend on the adapter or library version, so check its documentation. The pattern is stable: paths, methods, scopes, and per-path overrides such as disabling enforcement for a health check.

Path matching by hand

If your language has no ready library, a small matcher covers most cases. Longer, more specific patterns must win over wildcards:

JS Stand-in: path-to-resource and method-to-scope matching

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Caching and performance

Calling Keycloak on every request adds latency and load. Common mitigations:

  • Cache RPTs by user and requested permission for a short TTL (seconds to minutes).
  • Ask for all permissions once at login for UI decisions, but still enforce per request on the server.
  • Use response_mode=decision for simple checks to avoid generating tokens.
  • Keep resource lists small; use type-level permissions where you can.

Short TTLs mean revocations take effect quickly. Longer TTLs trade correctness for speed: decide per application.

Security notes

  • The RPT is a bearer token. Treat it like any access token: HTTPS, no logging, short life.
  • Validate aud: an RPT for invoice-api must not be accepted by another service.
  • Never trust permissions claimed by the client or decoded without signature checks.
  • Authorization for UI hints (hiding a button) is not enforcement. Always check on the server.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which grant type requests permissions from Keycloak?

    The UMA ticket grant takes the user's access token and returns an RPT or a decision.
  2. 2. What does response_mode=decision return?

    Decision mode skips token generation and gives a simple allow or deny.
  3. 3. Where in an RPT are granted resources and scopes listed?

    The authorization claim holds a permissions array with rsid, rsname, and scopes.
  4. 4. Why validate the aud claim of an RPT?

    Otherwise a token meant for another service could be replayed against yours.

Summary

  • The UMA ticket grant returns an RPT whose authorization.permissions lists granted resources and scopes.
  • response_mode chooses between full token, permissions list, or a simple decision.
  • A policy enforcer maps paths and methods to resources and scopes and handles caching.
  • Cache briefly, validate signature, issuer, audience, and expiry, and enforce on the server.

Next: Themes and Login Pages