How to create a new realm with the Keycloak REST API?

In this blog post I want to show, how to create a new realm with Keycloak REST API , because later I want to automate the Keycloak realm creation for a workshop using curl in a bash script. Here is a related blog post 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 .

keycloak-create-realm-01

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:

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.

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.

keycloak-create-realm-02

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.

keycloak-create-realm-03

  • Response:

The image below shows, now I got the 201 response and the new realm was created.

keycloak-create-realm-04

I verified the creation in the Keycloak server instance, and you see in the following image “it worked”.

keycloak-create-realm-05

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:


I hope this was useful for you and let’s see what’s next?

Greetings,

Thomas

Some of my related blog posts:

#IBMDeveloper,  #Keycloak, #RESTAPI

27 thoughts on “How to create a new realm with the Keycloak REST API?

Add yours

  1. 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?
    🙂

    Liked by 1 person

  2. 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.

    Like

    1. 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

      Like

  3. 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”)

    Liked by 1 person

    1. 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.

      Liked by 1 person

  4. 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}}

    Liked by 1 person

  5. 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.

    Like

  6. 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!

    Like

    1. 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

      Like

      1. 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!

        Like

      2. 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

        Like

  7. 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

    Like

  8. 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

    Like

    1. 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

      Like

  9. Very nice articles.
    One question: Can I create multiple keycloak resources in bulk for a single tenant? Is there an bulk provisioning options?

    Martin

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Blog at WordPress.com.

Up ↑

%d bloggers like this: