keycloakkeycloak-serviceskeycloak-rest-api

How can I programmatically create a permanent admin in Keycloak 26.1.2 using the Admin CLI?

I’m automating a Keycloak 26.1.2 installation and need to create a permanent admin (aka “superuser") entirely via shell script and the Admin CLI (kcadm.sh/kc.sh), not via the web UI. My installation script does the following steps:

1. Bootstrap temporary admin

kc.sh bootstrap-admin user --username:env KC_BOOTSTRAP_ADMIN_USERNAME --password:env KC_BOOTSTRAP_ADMIN_PASSWORD --no‑prompt

(per https://www.keycloak.org/server/bootstrap-admin-recovery)

2. Start Keycloak with:

kc.sh start ...

3. Import custom realm.json:

kc.sh import --file realm.json --override=false ...

4. Create permanent “super‑admin” user—fully automated, not via the web UI—that:

5. Cleanup: Delete the temporary bootstrap user once the permanent admin exists

I’m stuck on Step 4: how exactly do I grant this user the built‑in realm‑admin role (or equivalent full‑access roles) in both realms programmatically with kcadm.sh? All I’ve found online so far explains how to do it via the Admin Console UI, or only covers the temporary bootstrap user. I need the exact kcadm.sh add-roles (or other) invocation(s).

Question

How do I, in Keycloak 26.1.2, grant a non‑UI, script‑driven permanent admin user full administrative access to:

  1. The master realm
  2. A custom imported realm

using only kcadm.sh (and no interactive login)?

Solution

  • To grant an user full administrative privileges on both the master and a custom realm in Keycloak 26.1.2, you can leverage the fact that every realm in the master realm appears as a “client” with the name <realm name>-realm. By assigning realm-management roles on that client to your permanent admin user, you effectively give them full control over the target realm.

    Grant full “realm-admin” rights in the master realm:

    kcadm.sh add-roles \
  --uusername "${MASTER_REALM_PERMANENT_ADMIN_USERNAME}" \
  --rolename admin \
  ${ADMIN_CLI_OPTIONS}

    Grant full admin rights on your custom realm by targeting the <realm name>-realm client in the master realm. From Red Hat’s documentation:

    Admin users within the master realm can be granted management privileges to one or more other realms in the system. Each realm in Red Hat build of Keycloak is represented by a client in the master realm. The name of the client is <realm name>-realm.

    https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/server_administration_guide/admin_permissions#realm_specific_roles

    kcadm.sh add-roles \
  --uusername "${MASTER_REALM_PERMANENT_ADMIN_USERNAME}" \
  --cclientid "${CUSTOM_REALM_NAME}-realm" \
  --rolename create-client \
  --rolename impersonation \
  --rolename manage-authorization \
  --rolename manage-clients \
  --rolename manage-events \
  --rolename manage-identity-providers \
  --rolename manage-realm \
  --rolename manage-users \
  --rolename query-clients \
  --rolename query-groups \
  ${ADMIN_CLI_OPTIONS}

    # server, bootstrap admin user credentials, realm master, truststore etc.
${ADMIN_CLI_OPTIONS}

    What This Does