Postman and the Keycloak UserInfo endpoint

Revised article

This is a revised version of an article originally published on larsolino.dev on January 14, 2025.

The Keycloak UserInfo endpoint returns claims about the user associated with an access token. This guide uses Postman to obtain that token through the authorization code flow and then call UserInfo.

The original example used Keycloak 26.0.8 and Postman 11.27.4. The settings below use current client terminology and PKCE; interface labels may differ between versions.

Create an OpenID Connect client

Use a test realm and create a client with Client type: OpenID Connect and Client ID: postman-client.

For this desktop test, turn Client authentication off and Standard flow on. This makes Postman a public client using authorization code with PKCE. You do not need the separate Authorization feature, service accounts, implicit flow or direct access grants for UserInfo.

In Postman's OAuth settings, select Authorize using browser and copy the callback URL it displays into the client's Valid redirect URIs. Current Postman documentation lists https://oauth.pstmn.io/v1/browser-callback; older examples use /v1/callback. Register the exact URL used by your installed version, without a wildcard.

If the client exposes a Proof Key for Code Exchange Code Challenge Method setting, set it to S256. Save the client.

Confidential clients

To test an existing confidential client instead, leave client authentication enabled and supply its secret using the configured token endpoint authentication method. PKCE does not replace client authentication for a confidential client. Do not share or commit the secret.

Configure the request

Create a Postman environment with these values:

Variable	Example value
base_url	http://localhost:8180
realm	your-test-realm
client_id	postman-client

base_url is the Keycloak server address, not the Admin Console URL. Use HTTPS for a remote server.

Create a GET request:

{{base_url}}/realms/{{realm}}/protocol/openid-connect/userinfo

Under Authorization, select OAuth 2.0 and configure a new token:

Field	Value
Grant type	Authorization Code (With PKCE)
Code challenge method	SHA-256
Authorize using browser	Enabled
Callback URL	The exact URL registered above
Auth URL	{{base_url}}/realms/{{realm}}/protocol/openid-connect/auth
Access Token URL	{{base_url}}/realms/{{realm}}/protocol/openid-connect/token
Client ID	{{client_id}}
Client Secret	Empty for this public client
Scope	openid profile email

These endpoints can also be discovered from {{base_url}}/realms/{{realm}}/.well-known/openid-configuration. See Keycloak's OIDC endpoint reference.

Click Get New Access Token, complete the browser sign-in and choose Use Token. Configure Postman to add the token to the request headers, then send the GET request. The effective header is:

Authorization: Bearer <access_token>

Use the access token here, not the ID token. The openid scope is required for the OIDC UserInfo request.

Inspect the result

A response can look like this, depending on the user's data and configured client scopes:

{
  "sub": "ce7ca1f2-218e-4e87-bff8-3dc0adfe206c",
  "email_verified": true,
  "preferred_username": "siegurd",
  "name": "Siegurd Schnätterchen",
  "email": "[email protected]"
}

Group membership is not automatically part of this response. Follow Add group information to Keycloak UserInfo and tokens to configure a group membership mapper for this client.

Refresh and troubleshooting

Postman can refresh a token only if the provider issued a usable refresh token and the relevant client session is still valid. Enable its token auto-refresh option where available; sign in again if refresh is rejected. See Postman's OAuth 2.0 documentation for the behavior of your version.

Symptom	What to check
Invalid redirect URI	Compare the callback URL character for character with the registered URI.
invalid_client	Check client authentication and, for a confidential client, the secret and authentication method.
PKCE failure	Use S256/SHA-256 consistently and start a new authorization request.
401 Unauthorized	Check for a missing, expired or wrong-realm access token.
403 Forbidden	Check that the token was requested with openid; read the server error rather than assuming a client role is missing.
Missing profile or group claims	Check user data, requested scopes and the mapper's UserInfo setting.