Scribd
Upload
8 views

KEYCLOAK API

This guide details how to use the Keycloak REST API with Postman for managing users and groups, including obtaining access tokens and performing various API operations. It includes prerequisites, environment setup, and example requests for retrieving user and group information. Additionally, it addresses common errors and provides a reference for user and group IDs.

Uploaded by

Tarun Jaiswal
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
8 views

KEYCLOAK API

This guide details how to use the Keycloak REST API with Postman for managing users and groups, including obtaining access tokens and performing various API operations. It includes prerequisites, environment setup, and example requests for retrieving user and group information. Additionally, it addresses common errors and provides a reference for user and group IDs.

Uploaded by

Tarun Jaiswal
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 7

Keycloak REST API Guide

~by Ruthwick & Atharv

Introduction
This guide provides detailed instructions on how to interact with the Keycloak REST API using
Postman. It covers essential operations for managing users and groups, including retrieving user
and group information, getting group memberships, and more.

Prerequisites
• Keycloak server running (this guide uses a local instance at http://localhost:8080)
• Postman installed for API testing
• A realm created in Keycloak (this guide uses “poc-realm”)
• A client configured in the realm (this guide uses “node-api”)
• Admin user credentials

Environment Setup
Keycloak Configuration Details
• Server URL: http://localhost:8080
• Realm: poc-realm
• Client ID: node-api
• Client Secret: 4ngr5nmrM5Q8xrKWJwRzY4GEIMK1WYga
• Admin Username: admin-user
• Admin Password: 1234

Authentication: Getting an Access Token


Before performing any operation, you need to obtain an access token:
1. Create a new POST request in Postman

2. Set the URL:

http://localhost:8080/auth/realms/poc-realm/protocol/openid-
connect/token

Note: For Keycloak 17+, use: http://localhost:8080/realms/poc-


realm/protocol/openid-connect/token
3. Add header:

o Key: Content-Type
o Value: application/x-www-form-urlencoded
4. Add the following key-value pairs in the Body tab (x-www-form-urlencoded):

o client_id: node-api
o client_secret: 4ngr5nmrM5Q8xrKWJwRzY4GEIMK1WYga
o grant_type: password
o username: admin-user
o password: 1234
5. Send the request

6. Copy the access_token value from the response

Example response:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 300,
"refresh_expires_in": 1800,
"refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"not-before-policy": 0,
"session_state": "a1234567-1234-1234-1234-123456789abc",
"scope": "profile email"
}

API Operations
1. Get All Users
Retrieves a list of all users in the realm.
1. Create a new GET request in Postman

2. Set the URL:

http://localhost:8080/auth/admin/realms/poc-realm/users

Note: For Keycloak 17+, use: http://localhost:8080/admin/realms/poc-


realm/users
3. Add header:

o Key: Authorization
o Value: Bearer your-access-token-here (replace with the actual token)
4. Optional query parameters:

o ?briefRepresentation=false (for detailed user info)


o ?first=0&max=20 (for pagination)
o ?search=username (for searching users)
Example response:
[
{
"id": "275437d6-a095-454c-a4d6-4d815a1f8931",
"username": "admin-user",
"firstName": "admin",
"lastName": "user",
"email": "[email protected]",
"emailVerified": true,
"enabled": true,
"totp": false,
"disableableCredentialTypes": [],
"requiredActions": [],
"notBefore": 0
},
...
]

2. Get All Groups


Retrieves a list of all groups in the realm.
1. Create a new GET request in Postman

2. Set the URL:

http://localhost:8080/auth/admin/realms/poc-realm/groups

Note: For Keycloak 17+, use: http://localhost:8080/admin/realms/poc-


realm/groups
3. Add header:

o Key: Authorization
o Value: Bearer your-access-token-here (replace with the actual token)
Example response:
[
{
"id": "773fad75-4c5f-4332-a64a-c7a5c7b101c5",
"name": "poc",
"path": "/poc",
"subGroupCount": 0,
"subGroups": [],
"access": {
"view": true,
"viewMembers": true,
"manageMembers": true,
"manage": true,
"manageMembership": true
}
},
...
]

3. Get Specific Group Information


Retrieves detailed information about a specific group.
1. Create a new GET request in Postman

2. Set the URL (replace the group ID with your actual group ID):

http://localhost:8080/auth/admin/realms/poc-realm/groups/773fad75-4c5f-
4332-a64a-c7a5c7b101c5

Note: For Keycloak 17+, use: http://localhost:8080/admin/realms/poc-


realm/groups/773fad75-4c5f-4332-a64a-c7a5c7b101c5
3. Add header:

o Key: Authorization
o Value: Bearer your-access-token-here (replace with the actual token)

4. Get Users in a Specific Group


Retrieves all users that are members of a specific group.
1. Create a new GET request in Postman

2. Set the URL (replace the group ID with your actual group ID):

http://localhost:8080/auth/admin/realms/poc-realm/groups/773fad75-4c5f-
4332-a64a-c7a5c7b101c5/members

Note: For Keycloak 17+, use: http://localhost:8080/admin/realms/poc-


realm/groups/773fad75-4c5f-4332-a64a-c7a5c7b101c5/members
3. Add header:

o Key: Authorization
o Value: Bearer your-access-token-here (replace with the actual token)
4. Optional query parameters:

o ?briefRepresentation=false (for detailed user info)


o ?first=0&max=20 (for pagination)
5. Get Groups for a Specific User
Retrieves all groups that a specific user is a member of.
1. Create a new GET request in Postman

2. Set the URL (replace the user ID with your actual user ID):

http://localhost:8080/auth/admin/realms/poc-realm/users/275437d6-a095-
454c-a4d6-4d815a1f8931/groups

Note: For Keycloak 17+, use: http://localhost:8080/admin/realms/poc-


realm/users/275437d6-a095-454c-a4d6-4d815a1f8931/groups
3. Add header:

o Key: Authorization
o Value: Bearer your-access-token-here (replace with the actual token)

Troubleshooting Common Errors


401 Unauthorized
• Cause: Invalid or expired access token
• Solution: Get a new access token

Unable to find matching target resource method


• Cause: Incorrect URL or API endpoint structure
• Solution:
o Verify you’re using the correct URL format for your Keycloak version
o Check if the endpoint exists in your Keycloak version
o Make sure all IDs used in the URL are correct

HTTP 403 Forbidden


• Cause: The authenticated user doesn’t have sufficient permissions
• Solution: Use a user with the realm-admin role or appropriate permissions

API: - Get Groups for a Specific User


GET REQUEST: -
API: - http://localhost:8080/admin/realms/poc-realm/users/275437d6-a095-454c-a4d6-
4d815a1f8931/groups

WE HAVE TO PUT THE REQUIRED DETAILS AS SHOWS BELOW IN SNIPPET


RESPONSE:

User and Group IDs Reference


Users
Username User ID
admin-user 275437d6-a095-454c-a4d6-4d815a1f8931
api-admin-user d187d8e6-a22b-444c-8e4c-97506863aed4
full-access-user 3b37f8c9-d413-4149-8e35-9de17684ac1b
node-test-user d964efb8-ffac-480a-a022-ce67a563b7b0
react-admin-user 34fcf59f-b523-4035-8c1c-2f1953ce56c4
react-test-user 27c4a042-c9d0-408e-ba02-b4c2d9cb0675

Groups
Group Name Group ID
poc 773fad75-4c5f-4332-a64a-c7a5c7b101c5
test-group 7970d324-dff2-423e-8b2b-f6ad979c84f1
Conclusion
This guide provides the basic operations for interacting with Keycloak’s REST API for user and
group management. For more advanced operations, please refer to the official Keycloak
documentation.
Reference
https://www.keycloak.org/docs-api/latest/rest-api/openapi.json

You might also like