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.

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

#IBMDeveloper,  #Keycloak, #RESTAPI

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

  1. a says:

    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. G BHANU Prakash says:

    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

    • thomassuedbroecker says:

      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. G BHANU Prakash says:

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

    Like

  4. Warlord says:

    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

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 )

Google photo

You are commenting using your Google 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.