Keycloak UserInfo Endpoint: Fetch Claims After Login (2026)

The Keycloak UserInfo endpoint is not just a passive data store; it’s an active participant in your OAuth2/OIDC flow, dynamically serving claims based on the authenticated user and their granted scopes.

Let’s see it in action. Imagine a user logs into your application, which is configured with Keycloak as its identity provider. After successful authentication, your application receives an ID token and an access token. The access token is what unlocks the UserInfo endpoint.

Here’s a typical flow:

1. User Authentication: The user navigates to your application. Your application redirects them to Keycloak’s login page.
2. Keycloak Login: The user enters their credentials on Keycloak’s page.
3. Token Issuance: Upon successful login, Keycloak redirects the user back to your application with an authorization code. Your application exchanges this code for an ID token, an access token, and potentially a refresh token.
4. UserInfo Request: Your application, armed with the access token, makes a GET request to the Keycloak UserInfo endpoint, usually something like http://your-keycloak-domain/realms/your-realm/protocol/openid-connect/userinfo. The access token is passed in the Authorization header as a Bearer token.
5. Keycloak Response: Keycloak validates the access token. If valid and it has the necessary scopes (like openid or profile), it returns a JSON object containing claims about the authenticated user.

The actual request looks like this:

curl -X GET \
  'http://localhost:8080/realms/myrealm/protocol/openid-connect/userinfo' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiS'

And a successful response might look like:

{
  "sub": "a1b2c3d4-e5f6-7890-1234-abcdef123456",
  "email_verified": true,
  "name": "Jane Doe",
  "preferred_username": "janedoe",
  "given_name": "Jane",
  "family_name": "Doe",
  "email": "jane.doe@example.com"
}

This endpoint is crucial because it provides a standardized way to retrieve user attributes without needing to parse the ID token itself, which is intended for authentication and might have a limited set of claims based on the id_token scope. The UserInfo endpoint, on the other hand, is where you’d typically find claims associated with scopes like profile, email, address, and phone.

The primary problem this solves is decoupling sensitive or extensive user attribute retrieval from the initial authentication handshake. While the ID token is compact and designed for immediate verification, the UserInfo endpoint allows for a more dynamic and permissioned fetching of user data. Your application doesn’t need to request every possible user attribute in the initial login flow if it only needs a subset. Instead, it can request specific scopes (e.g., profile, email) and then use the access token to fetch the corresponding claims from the UserInfo endpoint after the user is authenticated. This granular control over data access is a cornerstone of modern identity management.

The claims returned by the UserInfo endpoint are determined by a combination of factors: the scopes requested in the original authorization request (which are reflected in the access token), and the configuration of the "User Info Mapper" within your Keycloak realm. Keycloak has default mappers for standard OIDC scopes (like openid, profile, email), but you can also create custom mappers to expose attributes stored in your user federation provider (like LDAP or Active Directory) or custom attributes you’ve added to Keycloak users. For instance, if you want to expose a department attribute, you’d typically configure a User Info Mapper in Keycloak that maps the department user attribute to a claim Keycloak will include in the UserInfo response.

A common misconception is that the ID token contains all user claims. In reality, the ID token is often limited to essential authentication claims and a subset of user attributes, primarily those associated with the openid scope. More detailed or sensitive information, like employment status or specific profile details, is typically fetched via the UserInfo endpoint, provided the access token has been granted the appropriate scopes (e.g., profile, custom_scope). The access token’s scope dictates which claims Keycloak is authorized to return from the UserInfo endpoint. If your access token doesn’t include the profile scope, for example, claims like name, given_name, and family_name will be absent from the UserInfo response, even if they exist for the user in Keycloak.

The next step in understanding user data access is exploring how to define and manage custom scopes and their corresponding claims.