Guide Updated

Keycloak JWT Issuer & Claims

Verify Keycloak JWTs. Keycloak's realm-specific issuer, JWKS URL, RS256 default, and the realm_access, resource_access, preferred_username claims explained with validation rules.

Keycloak is an open-source identity provider that issues JWTs for OAuth 2.0 and OpenID Connect. ID tokens and access tokens are both JWTs, signed with RS256 by default (configurable per realm). The issuer is realm-specific: https://YOUR_DOMAIN/realms/YOUR_REALM. Keycloak publishes its JWKS at /protocol/openid-connect/certs.

Issuer details

Property Keycloak
Issuer (iss)https://YOUR_DOMAIN/realms/YOUR_REALM
JWKS URLhttps://YOUR_DOMAIN/realms/YOUR_REALM/protocol/openid-connect/certs
OIDC discoveryhttps://YOUR_DOMAIN/realms/YOUR_REALM/.well-known/openid-configuration
Signing algorithmRS256 (default)

Issuer-specific claims

Claims you will encounter in Keycloak JWTs and what they mean for this issuer:

Claim Meaning for this issuer
isshttps://YOUR_DOMAIN/realms/YOUR_REALM: your Keycloak realm. Validate against your exact realm URL.
subThe user's Keycloak subject ID (a UUID). Stable across the realm.
preferred_usernameThe user's username (a human-readable display value). Do not use for authorization: use sub.
realm_accessAn object with a roles array: the realm-level roles assigned to the user. Check realm_access.roles for role-based authorization.
resource_accessAn object keyed by client ID, each with a roles array: the client-level roles. Check resource_access[clientId].roles for per-client authorization.
audThe client ID or audience configured for the token. Validate aud on every request.
azpAuthorized party: the client that requested the token. Present in token-exchange and some flows.
acrAuthentication Context Reference: the level of authentication performed (e.g. '1' for basic, '2' for MFA). Validate acr when your policy requires step-up auth.

Verifying tokens from this issuer

Fetch public keys from https://YOUR_DOMAIN/realms/YOUR_REALM/protocol/openid-connect/certs. Hardcode algorithms: ['RS256'] (or whichever you configured per realm: do not accept the default list). Validate iss against your realm URL and aud against your client ID. Keycloak rotates keys when configured; use a caching JWKS client that refetches on unknown kid. The Keycloak admin console shows active signing keys under Realm Settings → Keys.

Frequently asked questions

  • What is the Keycloak JWT issuer URL?

    The iss claim is realm-specific: https://YOUR_DOMAIN/realms/YOUR_REALM, where YOUR_DOMAIN is your Keycloak host and YOUR_REALM is the realm name. Validate iss against your exact realm. The JWKS endpoint is https://YOUR_DOMAIN/realms/YOUR_REALM/protocol/openid-connect/certs and the default signing algorithm is RS256 (configurable per realm).

  • How do I verify a Keycloak JWT?

    Fetch public keys from https://YOUR_DOMAIN/realms/YOUR_REALM/protocol/openid-connect/certs, verify the RS256 signature, and validate iss (your realm URL) and aud (your client ID). In Spring Boot, use OAuth2 Resource Server with jwk-set-uri set to the Keycloak JWKS URL. In Node.js use jose's createRemoteJWKSet. Keycloak rotates signing keys when configured: use a caching JWKS client that refetches on unknown kid.

  • How do I check roles in a Keycloak JWT?

    Realm-level roles are in realm_access.roles (an array of role names). Client-level roles are in resource_access[clientId].roles. After verifying the signature and claims, check that the required role is present in the appropriate array. For example, to require the 'admin' realm role: token.realm_access.roles.includes('admin'). Configure role mappings in the Keycloak admin console under the user or client.

Related