Keycloak Admin REST API is a set of endpoints that allows administrators to manage Keycloak realms, users, clients, and other resources programmatically. This API provides a powerful way to integrate Keycloak into your existing systems and automate repetitive tasks.

What is Keycloak Admin REST API?

Keycloak Admin REST API is a set of endpoints that allows administrators to manage Keycloak realms, users, clients, and other resources programmatically. This API provides a powerful way to integrate Keycloak into your existing systems and automate repetitive tasks.

💡 Key Point: The Admin REST API is crucial for automating identity and access management processes.

How do you authenticate with the Keycloak Admin API?

To interact with the Keycloak Admin REST API, you need to authenticate and obtain an access token. This token is used to authorize your API requests. You can authenticate using the client credentials grant type, which is suitable for server-to-server communication.

Wrong Way: Using Basic Authentication

Using basic authentication is not recommended because it sends your username and password in plain text over the network.

curl -X GET \
  http://localhost:8080/auth/admin/realms/master/users \
  -u admin:admin
⚠️ Warning: Avoid using basic authentication as it exposes your credentials.

Right Way: Using Client Credentials Grant Type

Create a client in Keycloak with the confidential access type and the client_credentials grant type. Then, use the following steps to obtain an access token.

  1. Create a client in the Keycloak admin console.
  2. Set the access type to confidential.
  3. Enable the Service Accounts Enabled option.
  4. Assign roles to the client if necessary.

Step-by-Step Guide

Create a client

Go to the Keycloak admin console, navigate to Clients, and create a new client.

Set access type

Set the access type to `confidential` and enable `Service Accounts Enabled`.

Assign roles

Assign necessary roles to the client for API access.

Obtain Access Token

curl -X POST \
  http://localhost:8080/auth/realms/master/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=admin-cli" \
  -d "client_secret=<your-client-secret>"

🎯 Key Takeaways

  • Use client credentials grant type for server-to-server communication.
  • Create a confidential client and enable service accounts.
  • Assign necessary roles to the client.

How do you list all users in a realm?

Listing all users in a realm is a common task when managing identities. You can achieve this by making a GET request to the /users endpoint.

curl -X GET \
  http://localhost:8080/auth/admin/realms/myrealm/users \
  -H "Authorization: Bearer <your-access-token>"

Handling Pagination

If there are many users, the API will paginate the results. You can control pagination using the first and max query parameters.

curl -X GET \
  http://localhost:8080/auth/admin/realms/myrealm/users?first=0&max=10 \
  -H "Authorization: Bearer <your-access-token>"

🎯 Key Takeaways

  • Use the `/users` endpoint to list all users.
  • Control pagination with `first` and `max` parameters.

How do you create a new user in a realm?

Creating a new user involves sending a POST request to the /users endpoint with the user details in JSON format.

Example: Creating a New User

curl -X POST \
  http://localhost:8080/auth/admin/realms/myrealm/users \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "email": "[email protected]",
    "enabled": true,
    "credentials": [
      {
        "type": "password",
        "value": "securepassword",
        "temporary": false
      }
    ]
  }'

Handling Errors

If the request fails, the API will return an error message. For example, if the username already exists, you might get the following response:

Terminal
$ curl -X POST http://localhost:8080/auth/admin/realms/myrealm/users -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"username": "johndoe", "email": "[email protected]", "enabled": true, "credentials": [{"type": "password", "value": "securepassword", "temporary": false}]}' {"errorMessage":"User exists with same username","error":"invalid_request"}

🎯 Key Takeaways

  • Use the `/users` endpoint to create new users.
  • Handle errors by checking the response status and message.

How do you update an existing user?

Updating an existing user involves sending a PUT request to the /users/{id} endpoint with the updated user details.

Example: Updating a User

First, find the user ID by listing all users or searching by username.

curl -X GET \
  http://localhost:8080/auth/admin/realms/myrealm/users?username=johndoe \
  -H "Authorization: Bearer <your-access-token>"

Then, update the user details using the user ID.

curl -X PUT \
  http://localhost:8080/auth/admin/realms/myrealm/users/<user-id> \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "enabled": true
  }'

🎯 Key Takeaways

  • Use the `/users/{id}` endpoint to update existing users.
  • Find the user ID before updating.

How do you delete a user?

Deleting a user involves sending a DELETE request to the /users/{id} endpoint.

Example: Deleting a User

First, find the user ID by listing all users or searching by username.

curl -X GET \
  http://localhost:8080/auth/admin/realms/myrealm/users?username=johndoe \
  -H "Authorization: Bearer <your-access-token>"

Then, delete the user using the user ID.

curl -X DELETE \
  http://localhost:8080/auth/admin/realms/myrealm/users/<user-id> \
  -H "Authorization: Bearer <your-access-token>"

🎯 Key Takeaways

  • Use the `/users/{id}` endpoint to delete users.
  • Find the user ID before deleting.

How do you list all realms?

Listing all realms is useful for managing multiple realms programmatically. You can achieve this by making a GET request to the /realms endpoint.

curl -X GET \
  http://localhost:8080/auth/admin/realms \
  -H "Authorization: Bearer <your-access-token>"

🎯 Key Takeaways

  • Use the `/realms` endpoint to list all realms.

How do you create a new realm?

Creating a new realm involves sending a POST request to the /realms endpoint with the realm configuration in JSON format.

Example: Creating a New Realm

curl -X POST \
  http://localhost:8080/auth/admin/realms \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "realm": "newrealm",
    "enabled": true,
    "displayName": "New Realm",
    "loginTheme": "base",
    "registrationAllowed": false,
    "rememberMe": false,
    "verifyEmail": false,
    "resetPasswordAllowed": false
  }'

🎯 Key Takeaways

  • Use the `/realms` endpoint to create new realms.
  • Provide necessary realm configuration in JSON format.

How do you update an existing realm?

Updating an existing realm involves sending a PUT request to the /realms/{realm-name} endpoint with the updated realm configuration.

Example: Updating a Realm

curl -X PUT \
  http://localhost:8080/auth/admin/realms/newrealm \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Updated New Realm",
    "registrationAllowed": true
  }'

🎯 Key Takeaways

  • Use the `/realms/{realm-name}` endpoint to update existing realms.
  • Provide updated realm configuration in JSON format.

How do you delete a realm?

Deleting a realm involves sending a DELETE request to the /realms/{realm-name} endpoint.

Example: Deleting a Realm

curl -X DELETE \
  http://localhost:8080/auth/admin/realms/newrealm \
  -H "Authorization: Bearer <your-access-token>"

🎯 Key Takeaways

  • Use the `/realms/{realm-name}` endpoint to delete realms.

Security Considerations

Security is paramount when working with the Keycloak Admin REST API. Here are some best practices to follow:

Secure the Admin Client

Ensure that the admin client is secured by setting appropriate access types and enabling service accounts.

Manage Access Tokens

Access tokens should be managed carefully. Store them securely and avoid hardcoding them in your source code.

Authenticate and Authorize Requests

All API requests must be authenticated and authorized. Use the client credentials grant type and assign necessary roles to the client.

🚨 Security Alert: Never expose your admin credentials or tokens in public repositories or logs.

Conclusion

Automating user and realm management in Keycloak using the Admin REST API can significantly improve efficiency and reduce manual errors. By following the steps outlined in this guide, you can effectively manage Keycloak resources programmatically. Remember to prioritize security by securing your admin client and managing access tokens properly.

💜 Pro Tip: This saved me 3 hours last week by automating user provisioning.

Start integrating the Keycloak Admin REST API into your workflows today to streamline your identity and access management processes.