kcadmでレルム・クライアント・ユーザを作る

目標

kcadmで、レルム、パブリッククライアント、機密クライアント、ユーザーをスクリプトで作成し、サービスアカウントのトークンまで受け取ってみます。

なぜ重要なのか

Keycloakの設定をWebコンソールで手作業で作ると、再現できません。ステージングで行った設定と本番で行った設定が静かに食い違い、数か月後に「本番でだけログインできない」ということになります。kcadmでスクリプト化すると、その設定がコードになり、レビューとバージョン管理の対象になります。そして、このラボで必ず理解しておくべき区別が、パブリッククライアントと機密クライアントです。シークレットを安全に保管できるかどうかで分かれ、この判断がどのグラントタイプを使うかを決めます。SPAに機密クライアントを作ってシークレットをJavaScriptのバンドルに入れることは、そのシークレットを公開するのと同じです。

KeycloakはJVMなので、起動が遅いです。このPodでは40–90秒ほどかかるため、ステップ1の待機ループが必須です。

ステップ

/root/kc/wait.shで、http://127.0.0.1:8080/realms/masterが200になるまで最大180秒待ってください。/root/kc/ready.txtにready_seconds=<정수>を書いてください(プレースホルダーは整数です)。
kcadm.sh config credentials --server http://127.0.0.1:8080 --realm master --user <관리자> --password <비밀번호>を実行してください(プレースホルダーは管理者のユーザー名とパスワードです)。資格情報は/opt/fixtures/kc/admin.envにあります。kcadm.sh get realmsが成功しなければなりません。
レルムlabhub2を有効な状態で作成してください。kcadm.sh get realms/labhub2のenabledがtrueでなければなりません。
パブリッククライアントweb-appを作成してください。publicClientはtrue、standardFlowEnabledはtrue、PKCEのコードチャレンジ方式はS256、リダイレクトURIはhttp://127.0.0.1:8161/callbackです。
機密クライアントapi-svcを作成してください。publicClientはfalse、serviceAccountsEnabledはtrueです。シークレットを/root/kc/api-svc.secretに保存してください。
ユーザーdev1を作成し、メールアドレスを設定して、パスワードをDev1!passで永続的に設定してください。kcadm.sh get users -r labhub2 -q username=dev1が1件を返さなければなりません。
api-svcでclient_credentialsのトークンを受け取り、/root/kc/svc-token.txtに保存してください。ドットが2つある文字列でなければなりません。
/root/kc/realm.jsonに、{"realm":"labhub2","clients":["web-app","api-svc"],"users":["dev1"]}の形の要約を作成してください。実際の取得結果を根拠に作成しなければなりません。

参考

kcadmのパスは、たいてい/opt/keycloak/bin/kcadm.shです。
レルムの作成: kcadm.sh create realms -s realm=labhub2 -s enabled=true
クライアントシークレットの取得: kcadm.sh get clients/<id>/client-secret -r labhub2
よくあるミス1: masterレルムにアプリケーションのユーザーを作ることです。Keycloakの管理権限と結びつきます。
よくあるミス2: パスワードを一時的(temporary)に設定して、最初のログインで変更画面が表示されることです。

Keycloakの準備を待つ

/root/kc/wait.shで、http://127.0.0.1:8080/realms/masterが200になるまで最大180秒待ってください。/root/kc/ready.txtにready_seconds=<정수>を書いてください(プレースホルダーは整数です)。

JVMの起動には時間がかかります。準備確認用のエンドポイントをポーリングしてください。最大180秒まで待って構いません。

管理者の資格情報を設定する

kcadm.sh config credentials --server http://127.0.0.1:8080 --realm master --user <관리자> --password <비밀번호>を実行してください(プレースホルダーは管理者のユーザー名とパスワードです)。資格情報は/opt/fixtures/kc/admin.envにあります。kcadm.sh get realmsが成功しなければなりません。

kcadmは、資格情報を一度設定すると、以降のコマンドで再利用します。管理アカウントの情報は、フィクスチャにあります。

アプリケーション用のレルムを作る

レルムlabhub2を有効な状態で作成してください。kcadm.sh get realms/labhub2のenabledがtrueでなければなりません。

masterにアプリケーションのユーザーを作ってはいけない理由は、読み物のレッスンにあります。有効化のオプションを忘れないでください。

パブリッククライアントを作る

パブリッククライアントweb-appを作成してください。publicClientはtrue、standardFlowEnabledはtrue、PKCEのコードチャレンジ方式はS256、リダイレクトURIはhttp://127.0.0.1:8161/callbackです。

シークレットのないクライアントには、PKCEが必須です。リダイレクトURIも、正確に登録する必要があります。

機密クライアントとサービスアカウントを作る

機密クライアントapi-svcを作成してください。publicClientはfalse、serviceAccountsEnabledはtrueです。シークレットを/root/kc/api-svc.secretに保存してください。

シークレットがあり、サービスアカウントを有効にすると、自分自身のトークンを受け取れます。シークレットをファイルとして保存しておいてください。

ユーザーを作成してパスワードを設定する

ユーザーdev1を作成し、メールアドレスを設定して、パスワードをDev1!passで永続的に設定してください。kcadm.sh get users -r labhub2 -q username=dev1が1件を返さなければなりません。

ユーザーの作成とパスワードの設定は、別々のコマンドです。一時的なパスワードでなければ、ログインのフローが止まりません。

サービスアカウントのトークンを受け取る

api-svcでclient_credentialsのトークンを受け取り、/root/kc/svc-token.txtに保存してください。ドットが2つある文字列でなければなりません。

ユーザーなしで、クライアントの資格情報だけで受け取るフローです。グラントタイプの名前を正確に書いてください。

レルム構成の要約を残す

/root/kc/realm.jsonに、{"realm":"labhub2","clients":["web-app","api-svc"],"users":["dev1"]}の形の要約を作成してください。実際の取得結果を根拠に作成しなければなりません。

作ったものを取得して、1つのファイルにまとめます。他の人が再現できる形でなければなりません。