Creating Realms, Clients and Users With kcadm

Goal

With kcadm, create a realm, a public client, a confidential client, and a user by script, and even obtain a service account token.

Why it matters

If you create Keycloak settings by hand in the web console, they are not reproducible. The settings made in staging and those made in production quietly diverge, and a few months later it becomes "login doesn't work only in production". If you script it with kcadm, those settings become code and subject to review and version control. And a distinction you must understand in this lab is between public and confidential clients. It splits on whether you can keep a secret safe, and this judgment decides which grant type to use. Creating a confidential client for an SPA and putting its secret in the JavaScript bundle is the same as publishing that secret.

Keycloak is a JVM, so startup is slow. In this Pod it takes about 40–90 seconds, so the wait loop in step 1 is essential.

Steps

With /root/kc/wait.sh, wait up to 180 seconds until http://127.0.0.1:8080/realms/master returns 200. In /root/kc/ready.txt, write ready_seconds=<정수> (an integer).
Run kcadm.sh config credentials --server http://127.0.0.1:8080 --realm master --user <관리자> --password <비밀번호> (the administrator and the password). The credentials are in /opt/fixtures/kc/admin.env. kcadm.sh get realms must succeed.
Make the realm labhub2 active. In the output of kcadm.sh get realms/labhub2, enabled must be true.
Create the public client web-app. publicClient is true, standardFlowEnabled is true, the PKCE code challenge method is S256, and the redirect URI is http://127.0.0.1:8161/callback.
Create the confidential client api-svc. publicClient is false and serviceAccountsEnabled is true. Save the secret to /root/kc/api-svc.secret.
Create the user dev1, set an email, and permanently set the password to Dev1!pass. kcadm.sh get users -r labhub2 -q username=dev1 must return 1 item.
Using api-svc, get a client_credentials token and save it to /root/kc/svc-token.txt. It must be a string with 2 dots.
In /root/kc/realm.json, create a summary in the form {"realm":"labhub2","clients":["web-app","api-svc"],"users":["dev1"]}. It must be written based on actual lookup results.

Notes

The kcadm path is usually /opt/keycloak/bin/kcadm.sh.
Create a realm: kcadm.sh create realms -s realm=labhub2 -s enabled=true
Look up a client secret: kcadm.sh get clients/<id>/client-secret -r labhub2
Common mistake 1: creating application users in the master realm — they get entangled with Keycloak administration permissions.
Common mistake 2: setting the password as temporary so that a change screen appears at first login.

Wait for Keycloak to be ready

With /root/kc/wait.sh, wait up to 180 seconds until http://127.0.0.1:8080/realms/master returns 200. In /root/kc/ready.txt, write ready_seconds=<정수> (an integer).

The JVM takes time to start. Poll the readiness endpoint. You may wait up to 180 seconds.

Set the administrator credentials

Run kcadm.sh config credentials --server http://127.0.0.1:8080 --realm master --user <관리자> --password <비밀번호> (the administrator and the password). The credentials are in /opt/fixtures/kc/admin.env. kcadm.sh get realms must succeed.

Once you set the credentials, kcadm reuses them in later commands. The administrator account information is in the fixtures.

Create the application realm

Make the realm labhub2 active. In the output of kcadm.sh get realms/labhub2, enabled must be true.

The reading material explains why you must not create application users in master. Do not forget the enable option.

Create a public client

Create the public client web-app. publicClient is true, standardFlowEnabled is true, the PKCE code challenge method is S256, and the redirect URI is http://127.0.0.1:8161/callback.

PKCE is mandatory for a client without a secret. You must also register the redirect URI precisely.

Create a confidential client and a service account

Create the confidential client api-svc. publicClient is false and serviceAccountsEnabled is true. Save the secret to /root/kc/api-svc.secret.

With a secret and the service account turned on, it can obtain its own token. Save the secret to a file.

Create a user and set the password

Create the user dev1, set an email, and permanently set the password to Dev1!pass. kcadm.sh get users -r labhub2 -q username=dev1 must return 1 item.

Creating a user and setting a password are separate commands. The password must not be temporary so that the login flow is not blocked.

Get a service account token

Using api-svc, get a client_credentials token and save it to /root/kc/svc-token.txt. It must be a string with 2 dots.

It is a flow that obtains a token with only the client's credentials, without a user. Write the grant type name exactly.

Leave a summary of the realm configuration

In /root/kc/realm.json, create a summary in the form {"realm":"labhub2","clients":["web-app","api-svc"],"users":["dev1"]}. It must be written based on actual lookup results.

Look up what you created and gather it into one file. It must be in a form that others can reproduce.