Create a Keycloak Realm Using Admin REST API

Keycloak provides a fully functional Admin REST API.

Pre-requisites

  1. A running instance of Keycloak with admin credentials.
  2. curl package.
  3. jq package (see https://stedolan.github.io/jq/download/).

Create a New Realm

Configure the environment, change the details as required to match your system.

NEW_REALM="example"
KEYCLOAK_URL=http://127.0.0.1:8080
KEYCLOAK_REALM="master"
KEYCLOAK_USER="admin"
KEYCLOAK_SECRET="changeme"
REALM_FILE="realm.json";
CURL_CMD="curl --silent --show-error"

Content of the file realm.json can be seen below.

{
   "realm":"example",
   "notBefore":0,
   "enabled":true,
   "sslRequired":"all",
   "bruteForceProtected":true,
   "failureFactor":10,
   "eventsEnabled":false
}

Obtain Access Token

Obtain the access token:

ACCESS_TOKEN=$(${CURL_CMD} \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=${KEYCLOAK_USER}" \
  -d "password=${KEYCLOAK_SECRET}" \
  -d "grant_type=password" \
  -d 'client_id=admin-cli' \
  "${KEYCLOAK_URL}/auth/realms/${KEYCLOAK_REALM}/protocol/openid-connect/token"|jq -r '.access_token')

The response body is JSON, we use jq to extract the value of the access_token property. I’ve seen people using sed, I think that jq is easier.

Optionally, check the token:

echo ${ACCESS_TOKEN}

Create a new realm:

${CURL_CMD} \
  -X POST \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @"${REALM_FILE}" \
  "${KEYCLOAK_URL}/auth/admin/realms";

Verify that the realm has been created:

${CURL_CMD} \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  "${KEYCLOAK_URL}/auth/admin/realms/${NEW_REALM}"|jq -r .|head;

API Examples

These are API examples and not a real configuration.

Content of the file client.json can be seen below.

{
   "clientId":"example",
   "rootUrl":"https://example.com/example/",
   "adminUrl":"https://example.com/example/"
}

Create a new client:

CLIENT_FILE="client.json";
${CURL_CMD} \
  -X POST \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @"${CLIENT_FILE}" \
  "${KEYCLOAK_URL}/auth/admin/realms/${NEW_REALM}/clients";

Update the top-level information of the realm:

${CURL_CMD} \
  -X PUT \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @"${NOT_A_REAL_FILE_JUST_AN_EXAMPLE}" \
  "${KEYCLOAK_URL}/auth/admin/realms/${NEW_REALM}";

Create a new Identity Provider instance:

${CURL_CMD} \
  -X POST \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @"${NOT_A_REAL_FILE_JUST_AN_EXAMPLE}" \
  "${KEYCLOAK_URL}/auth/admin/realms/${NEW_REALM}/identity-provider/instances";

Create a new Identity Provider Mapper:

${CURL_CMD} \
  -X POST \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @"${NOT_A_REAL_FILE_JUST_AN_EXAMPLE}" \
  "${KEYCLOAK_URL}/auth/admin/realms/${NEW_REALM}/identity-provider/instances/${IDP_ALIAS}/mappers";

Create a new authentication flow config:

${CURL_CMD} \
  -X POST \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @"${NOT_A_REAL_FILE_JUST_AN_EXAMPLE}" \
  "${KEYCLOAK_URL}/auth/admin/realms/${NEW_REALM}/authentication/flows";

Raise execution priority:

${CURL_CMD} \
  -X POST \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  "${KEYCLOAK_URL}/auth/admin/realms/${NEW_REALM}/authentication/executions/${EXECUTION_ID}/raise-priority";

Add a new authentication execution:

${CURL_CMD} \
  -X POST \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @"${NOT_A_REAL_FILE_JUST_AN_EXAMPLE}" \
  "${KEYCLOAK_URL}/auth/admin/realms/${NEW_REALM}/authentication/executions";

References

https://www.keycloak.org/docs-api/11.0/rest-api/index.html

4 thoughts on “Create a Keycloak Realm Using Admin REST API

  1. Having a small, working example of a realm representation has helped me immensely. Readable cURL examples (instead of Postman screen shots – ugh!) also helps. Thank you!
    You might want to note that the base URL for the realms API is now ${KEYCLOAK_URL}/admin/realms (omit “/auth”)

Leave a Reply

Your email address will not be published. Required fields are marked *