In this blog post I want to show, how to create a new realm with Keycloak REST API (Version 10) , because later I want to automate the Keycloak realm creation for a workshop using curl in a bash script. The Keycloak REST API has changed a bit, here is a related blog post for a newer version of Keycloak: How to create a new realm with Keycloak in Version 20.0.1, REST API and cURL?
The reason of that blog post is, that the information in the REST API documentation wasn’t detailed enough for me. The image shows what I found first in the Keycloak REST API documentation .
In common it’s very simple to use the Keycloak REST API. For more details see in my blog post Getting started to secure a simple Java Microservice with Keycloak, MicroProfile and OpenLiberty.
First you need a bearer authorization token for an administration user and with that token you create a new realm using the realm json exported before.
Here is what I found:
- … for the Authorization user for administrative tasks, I got the missing pieces in the Keycloak documentation here.
- … for the submit of the realm json, I got the missing pieces as a part of the answer on StackOverflow “Unable to create Keycloak realm via the rest admin API: Unsupported Media Type“.
I used POSTMAN to check it out. These are the steps I did in POSTMAN.
1. Authorize user for administrative tasks
These are the values I used for the REST API POST request to get the access_token.
In the following section you see the URL structure, the needed header and body with the values I used and also the response of the request.
- RESTful command: POST
- URL: https://KEYCLOAKSERVER/auth/realms/master/protocol/openid-connect/token
- Header:
| Key | Value |
| Content-Type | application/x-www-form-urlencoded |
- Body:
| Key | Value |
| grant_type | password |
| client_id | admin-cli |
| username | admin |
| password | admin |
- Response:
The image shows request response with the access_token, I used for the next realm creation request.
2. Create the realm
These are the values I used for the POST request to get the new realm.
In the following section you see the URL structure, the needed header and body with the values I used and also the response of the request.
- RESTful command: POST
- URL: https://KEYCLOAKSERVER/auth/admin/realms
- Header:
Copy the access_token value and past the token value into the authorization.
| Key | Value |
| Authorization | bearer access_token value |
| Content-Type | application/x-www-form-urlencoded |
- Body:
| raw | JSON(application/json) |
The image shows the body with the realm json, I used to create the new realm.
- Response:
The image below shows, now I got the 201 response and the new realm was created.
I verified the creation in the Keycloak server instance, and you see in the following image “it worked”.
Additional resources
Because of the often requests in the comments. Here are the links to the example I used and a YouTube video I made:
- Realm JSON file
- Useful bash script for automation
- GitBook with the setup of an example application
- YouTube Video (setup starts at 3:18 min)
I hope this was useful for you and let’s see what’s next?
Greetings,
Thomas
Some of my related blog posts:
- Upload an user to Keycloak using CURL
- Map an existing user to a role in a Keycloak realm using CURL
- Simply logout from Keycloak
#IBMDeveloper, #Keycloak, #RESTAPI
Thomas Suedbroecker's Blog 
Your article was very helpful.
We want to create a realm by receiving a token using the master realm’s matser-realm client.
At this point, I get a 403 unauthorized. But, it works well with the token of admin-cli client.
Do you know how to create a realm with the master-realm’s client token?
🙂
LikeLiked by 1 person
Thanks for your awesome feedback, but I haven’t used „master-realm“. I also would have to search for it 😉 .
As I understand the admin-cli is the way to do admin tasks, like creating a realm.
https://www.keycloak.org/docs/latest/server_admin/#the-admin-cli
Have a nice WE Greetings Thomas
LikeLike
I have an end to end automation on Keycloak API with Curl commands.Can u suggest any Curl commands to create client with protocol mapper.
LikeLike
Hi Bhanku,
Hmm no … I can only share my bash script for the automation I did, maybe that helps a bit …
#!/bin/bash# Set the needed parameter
USER=admin
PASSWORD=admin
GRANT_TYPE=password
CLIENT_ID=admin-cli
#INGRESSURL="YOUR URL"
echo "------------------------------------------------------------------------"
echo "Your INGRESSURL for Keycloak: https://$INGRESSURL"
echo "------------------------------------------------------------------------"
echo ""
# Get the bearer token from Keycloak
echo "------------------------------------------------------------------------"
echo "Get the bearer token from Keycloak"
echo "------------------------------------------------------------------------"
echo ""
access_token=$( curl -d "client_id=$CLIENT_ID" -d "username=$USER" -d "password=$PASSWORD" -d "grant_type=$GRANT_TYPE" "https://$INGRESSURL/auth/realms/master/protocol/openid-connect/token" | sed -n 's|.*"access_token":"\([^"]*\)".*|\1|p')
# Create the realm in Keycloak
echo "------------------------------------------------------------------------"
echo "Create the realm in Keycloak"
echo "------------------------------------------------------------------------"
echo ""
result=$(curl -d @./quarkus-realm.json -H "Content-Type: application/json" -H "Authorization: bearer $access_token" "https://$INGRESSURL/auth/admin/realms")
if [ "$result" = "" ]; then
echo "------------------------------------------------------------------------"
echo "The realm is created."
echo "Open following link in your browser:"
echo "https://$INGRESSURL/auth/admin/master/console/#/realms/quarkus"
echo "------------------------------------------------------------------------"
else
echo "------------------------------------------------------------------------"
echo "It seems there is a problem with the realm creation: $result"
echo "------------------------------------------------------------------------"
fi
Greetings, Thomas
LikeLike
Thank you for your script. Its working manually. When i do the curl, i am getting 401 unauthorized.
It seems there is a problem with the realm creation: {“error”:”HTTP 401 Unauthorized”}
I used below script:-
================
USER=admin
PASSWORD=Pa55w0rd
GRANT_TYPE=password
CLIENT_ID=admin-cli
INGRESSURL=”15.265.96.27:31398″
access_token=$( curl -d “client_id=$CLIENT_ID” -d “username=$USER” -d “password=$PASSWORD” -d “grant_type=$GRANT_TYPE” “http://$INGRESSURL/auth/admin/realms/master/protocol/openid-connect/token” | sed -n ‘s|.*”access_token”:”\([^”]*\)”.*|\1|p’)
result=$(curl -d @./bo_realm-realm.json -H “Content-Type: application/json” -H “Authorization: bearer $acess_token” “http://$INGRESSURL/auth/admin/realms”)
LikeLiked by 1 person
Your article was very helpful in completing the automation task with importing realm with your script. i have added scope,credential type and nonce values and realm got successfully created.
Great thanks to you.
LikeLiked by 1 person
Thanks for your feedback, Greetings Thomas
LikeLike
Greate Article,
Can you please share the json file for the realm body as text ?
LikeLiked by 1 person
Hi, here is the setup in a gitbook project …
https://ibm-developer.gitbook.io/get-started-with-security-for-your-java-microservi/authentication-and-authorization-with-keycloak-and-quarkus/app-sec-exercise-01 …
I hope it helps … greetings Thomas
LikeLiked by 1 person
Hi sir,
Can you please share with me the JSON file for the realm body as text?
Mail id : mjreddy1229@gmail.com
Need this one ASAP sir…please help me
LikeLiked by 1 person
@Janardhan, here is the link to the github repository: https://github.com/IBM/cloud-native-starter/blob/master/security/IKS/quarkus-realm.json
And this is the link to the setup of the example: https://ibm-developer.gitbook.io/get-started-with-security-for-your-java-microservi/authentication-and-authorization-with-keycloak-and-quarkus/app-sec-exercise-01
Have success and greetings,
Thomas
LikeLiked by 1 person
This was very useful, thanks for the post.
I thought it might be useful to others to grab the JSON required to create a realm by querying it from another using GET.
Using the VSCode api rest client I make the calls like this:
# @name get_token
POST https://sso.{{$dotenv HOST}}.{{$dotenv DOMAIN}}/auth/realms/master/protocol/openid-connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
grant_type=password&client_id=admin-cli&username=admin&password={{$dotenv KEYCLOAK_PASSWORD}}
# @name show_realm
@access_token = {{get_token.response.body.access_token}}
GET https://sso.{{$dotenv HOST}}.{{$dotenv DOMAIN}}/auth/admin/realms/master
Content-Type: application/json
Authorization: bearer {{access_token}}
LikeLiked by 1 person
Thanks for your feedback
LikeLiked by 2 people
Thanks for the post very helpful, Keykloak need more resources and example for it API ! Just something, Part 2 give an header “Content-Type : form encoded”, but you describe a JSON format to create the realms (and you precise it very well in the next line !).
Just saying 😉 Thanks mate.
LikeLike
Hey Thomas, nice post, really helpful. I’m new with Keycloak and this post is helping me to automate the setup and I’ve a question if may I ask, I’m using Keycloak as Key Manager of WSO2 but if I create an user on another Realm other than Master, I get “401 Unauthorized” from Keycloak, Do you have any idea on where to start to look?.
Thanks!
LikeLike
Hi Bruno,
did you check out these blog posts?
I hope I got your question right? You want to upload users as admin, right?
* UPLOAD AN USER TO KEYCLOAK USING CURL
https://suedbroecker.net/2021/07/16/upload-an-user-to-keycloak-using-curl/
* MAP AN EXISTING USER TO A ROLE IN A KEYCLOAK REALM USING CURL
https://suedbroecker.net/2021/08/18/map-an-existing-user-to-a-role-in-a-keycloak-realm-using-curl/
Maybe that helps. This is the way I used to upload an existing user to another realm.
Greetings, Thomas
LikeLike
Thomas, thanks for your reply; yes I’m trying something like that, maybe I don’t express me well, my English expertise is as with Keycloak 😉
I’ve this example, https://apim.docs.wso2.com/en/latest/administer/key-managers/configure-keycloak-connector/, automated with cURL API calls to Keycloak, but in this post, your approach seems more easy, I’ve tried and it works fine, but I can’t get a Token from Keycloak through WSO2 if the Keycloak user is created in another Realm than Master, it fails with “401 Unauthorized”.
So, I will look your examples and try to do a partial import with the client, client scopes and service account roles in a JSON file to the Master Realm, since its looks more easy in that way.
Thanks again!
LikeLike
Hi Bruno,
I see this documentation does really start with the basics, that means to secure the communication by creating certificates and so on.
My blog posts do only focus on specific objectives.
I am happy that my blog posts are useful for you.
Greetings Thomas
LikeLike
Hello THOMASSUEDBROECKER,
This document is very helpful thank you very much for this.
I am new to keyclaok and i just started learning this tool. Now in my task, i need to add some attribute in user registration page like user address, ID number.
I know how to add this, i just need to write code in register file but as per requirement i need to pass api to next team.
So i don’t know how to write and pass api for this. Could you please help me on this.
if possible please help.
email id:- dur2307@gamil.com
LikeLike
Hello THOMASSUEDBROECKER,
This document is very helpful thank you very much for this.
I am new to keyclaok and i just started learning this tool. Now in my task, i need to add some attribute in user registration page like user address, ID number.
I know how to add this, i just need to write code in register file but as per requirement i need to pass api to next team.
So i don’t know how to write and pass api for this. Could you please help me on this.
if possible please help.
email id:- dur2307@gmail.com
LikeLike
Hi @Durgesh,
as far as I understand you need to customize the login, registration template, right?
I would say it would be good, if you first separate what a registration at your application needs and what does Keycloak manage “out of the box” for your user, relevant for the authentication.
I would say a good starting point this kind of understanding how to do a customization of a layout for the registration is this blog post https://www.baeldung.com/keycloak-user-registration.
Maybe this is a good starting point for you. I hope this helps a bit.
Regards,
Thomas
LikeLike
Very nice articles.
One question: Can I create multiple keycloak resources in bulk for a single tenant? Is there an bulk provisioning options?
Martin
LikeLike
Hmm, I am not sure what you mean. With the automation you can create as much as you want.
Here is on blog post about multi tenancy https://suedbroecker.net/2021/08/20/use-of-quarkus-security-openid-connect-multi-tenancy-in-an-own-small-example/ Maybe that helps a bit. Greetings Thomas
LikeLike