This tutorial will show you how to query the Keycloak UserInfo endpoint with Postman and the Authorization Code Flow. We will explore the process of setting up a Postman environment, requesting an access token through Authorization Code, and retrieving a JSON response from the UserInfo endpoint.

Keycloak is supposed to run under http://localhost:8180/admin. This should be adjusted to your needs.

Overview

We’ll go through the following steps:

  1. Setting up Keycloak and creating a client
  2. Configuring a Postman environment
  3. Requesting an access token using Authorization Code Flow
  4. Querying the UserInfo endpoint
  5. Automating the process for future use

Step 1: Create an OpenID Connect client

To interact with Keycloak from Postman, we must set up a client in the Keycloak Admin Console.

  1. Log in to the Keycloak Admin Console at http://localhost:8180/admin.
  2. Navigate to Clients and click Create.
  3. Configure the client with the following details:
  • Client ID: postman-client
  • Client Protocol: openid-connect
  • Access Type: confidential
  1. Click Save.

Next, configure the client for Authorization Code Flow:

  1. In the client settings, ensure Authorization Enabled is set to On.
  2. Under the Credentials tab, copy the Client Secret.
  3. Go to the Redirect URIs section and add Postman’s callback URL:
https://oauth.pstmn.io/v1/callback

💡 If Keycloak is running locally, make sure the client’s root and base URLs

Step 2: Create a Postman environment

Create a Postman environment to store your Keycloak configuration.

  1. In Postman, go to Environments and click New.
  2. Name the environment Keycloak Environment.
  3. Add the following variables:
Variable Initial Value
base_url http://localhost:8180
realm your-realm-name
client_id your-client-id
client_secret your-client-secret

Step 3: Request an access token using the Authorization Code Flow

Now, let’s configure Postman to request an access token via the Authorization Code Flow.

  1. In Postman, create a new GET request.
  2. Set the URL to:
{{base_url}}/realms/{{realm}}/protocol/openid-connect/userinfo
  1. Go to the Authorization tab.
  2. From the Type dropdown, select OAuth 2.0.
  3. Click Get New Access Token and fill in the following details:
Field Value
Grant Type Authorization Code
Callback URL https://oauth.pstmn.io/v1/callback
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 {{client_secret}}
Scope openid profile email
  1. Click Request Token.

You will be redirected to the Keycloak login page. Enter your username and password, and approve the request.

  1. Once you receive the token, click Use Token.

Step 4: Query the UserInfo endpoint

With your access token applied, you can now query the UserInfo endpoint.

  1. Ensure your GET request URL is set to:
{{base_url}}/realms/{{realm}}/protocol/openid-connect/userinfo
  1. Click Send.

If successful, you should see a JSON response similar to this:

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

💡 The example above does include group memberships, which requires additional configuration.

Step 5: Automating token refresh (optional)

To streamline the process for future use, Postman can auto-refresh your token when it expires:

  1. Go to the Authorization tab.
  2. Enable Auto-refresh token before it expires.

This will ensure your token is always valid when making requests.

Common errors and troubleshooting

Error Cause Solution
401 Unauthorized Invalid or missing token Ensure the token is valid and applied correctly
403 Forbidden Client is not authorized to use the endpoint Check your client’s permissions in Keycloak
Invalid Redirect URI Redirect URI in Keycloak doesn’t match Postman Ensure the callback URL in Keycloak is correct