Keycloak provides a fully functional Admin REST API.
Pre-requisites
- A running instance of Keycloak with admin credentials.
- curl package.
- 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
This has been very helpfulĀ taming the admin interface, thanks!
how to set Failure Reset Time
Hi Sunny, what have you tried so far?
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”)