Keycloak New Security Admin Console 開発の一歩
Keycloakは現在、セキュリティ管理コンソールを新しいコンソールに切り替えを行おうとしています。
Keycloak v21.0では旧のセキュリティ管理コンソールは削除される予定です。
今回は年末年始にKeycloakの新しいセキュリティ管理コンソールの改修を行ったので、その過程を記載しようと思います。
きっかけ
GitHubでこちらのDiscussionを見かけました。
確かにこの設定は新しいセキュリティ管理コンソールにありませんでした。
無いなら追加してみようと思いましたが、New Admin Consoleについてはどうやって改修すればいいの？みたいになったので、色々と調べながら修正を行っていきました。
Keycloak GitHub リポジトリ
まずKeycloakの新しいUIについてですが、リポジトリは keycloak-ui で管理されています。 Keycloakにはおおきくわけると2つのUIがあり、このリポジトリで管理されています。
- Account UI
- アカウントコンソール(一般利用者向け)
- Admin UI
- セキュリティ管理コンソール(管理者向け)
今回はIdentity Brokerという他のOpenID Providerに認証を向ける管理者向けの設定の部分なので、後者の方の対応となります。
このリポジトリをForkし、git cloneでコードをローカルPCに取得します。
git clone https://github.com/i7a7467/keycloak-ui.git
cd keycloak-ui
keycloak-ui の開発環境準備
開発環境の準備についてはこちらに記載されています。
こちらの準備を実施すると、このような環境が出来上がります。
UIの開発の確認は左のサーバーにアクセスして確認していくことになります。
必要なもの
- Node.js 18.0以上
- Keycloakの起動に必要なOpenJDK 11(それ以上のバージョンのJDK)
- Keycloak 22.0 から最新のOpenJDK LTSのみをサポートすることが計画されています。
- そのため、Keycloak 22.0ではOpenJDK 17のみがサポート対象となります。
開発環境Keycloak-serverの起動
まずはkeycloak-serverから起動します。
kcuser@example keycloak-ui % cd apps/keycloak-server
kcuser@example keycloak-server % npm run start
> start
> ./scripts/start-server.mjs
Downloading and extracting server…
(node:4057) ExperimentalWarning: The Fetch API is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
Starting server…
Updating the configuration and installing your custom providers, if any. Please wait.
2023-02-02 23:47:36,734 INFO [org.keycloak.common.Profile] (build-106) Preview features enabled: admin-fine-grained-authz, declarative-user-profile
2023-02-02 23:47:42,823 INFO [io.quarkus.deployment.QuarkusAugmentor] (main) Quarkus augmentation completed in 7693ms
...
今回はAdmin UIの開発なので起動させたkeycloak-serverに開発用Admin UIがアクセスできるようにクライアントの登録を行う必要があります。
cd keycloak-ui/apps/keycloak-server/scripts
npm run import-client
> import-client
> wireit
✅ [../../libs/keycloak-admin-client:build] Restored from cache
🏃 [import-client] Running command "./scripts/import-client.mjs"
(node:4697) ExperimentalWarning: The Fetch API is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
Importing client…
Client imported successfully.
✅ [import-client] Executed successfully
上述のコマンドを実行することで以下のようにKeycloak serverに security-admin-console-v2 のクライアントが登録されます。Home URLが http://localhost:8080になっています。
Keycloak-serverのポートでも、セキュリティ管理コンソールにはアクセスできますので、以下のように確認可能です。
開発環境keycloak-uiの起動
続いて、コード修正しながらセキュリティ管理コンソールを確認できるようにkeycloak-uiを起動します。
kcuser@example keycloak-ui % cd apps/admin-ui
kcuser@example admin-ui % npm run dev
> dev
> wireit
✅ [../../libs/keycloak-admin-client:build] Already fresh
✅ [../../libs/keycloak-js:build] Restored from cache
🏃 [dev] Running command "vite --host"
VITE v3.2.5 ready in 1489 ms
➜ Local: http://localhost:8080/
➜ Network: http://192.168.3.2:8080/
http://localhost:8080 で開発者用のセキュリティ管理コンソールにアクセスできます。
あくまでkeycloak-serverのクライアントとして登録されているので、ログインするときはKeycloak-serverのログイン画面(8180ポート)になります。
これで開発環境の準備は整いました。次に修正する内容のissueを起票しましょう。
続いてコードの修正をします。
セキュリティ管理コンソールの改修
keycloak-uiは React と PatternFly4 で書かれています。
赤帽エンジニアブログにPatternFly4について書かれている記事があります。
今回はこちらのブログとPatternFly4の公式サイトを参考にして、コードの修正を行いました。
開発環境ではViteが使われており、ホットリロードが行われ、修正した内容をすぐ確認できるようになっています。コーディング規約はこちらです。
e2eテストの実装
keycloak-uiのリポジトリではe2eテストとして、cypressが使われています。
cypressによるテストコードの書き方についてもこちらで記載されています。
以下のコマンドを実行するとcypressのテストを実行することができます。
kcuser@example keycloak-ui % cd apps/admin-ui
kcuser@example admin-ui % npm run cy:open
> cy:open
> cypress open --e2e --browser chrome
Still waiting to connect to Chrome, retrying in 1 second (attempt 18/62)
Still waiting to connect to Chrome, retrying in 1 second (attempt 19/62)
GET /chrome-variations/seed?osname=mac&channel=stable&milestone=109 200 938.554 ms - -
cypressのコンソールが起動するので、テスト対象のファイルを選択するとテストを実行できます。
PRの作成
PRを作成し、レビューを受けます。
さいごに
keycloakの新セキュリティ管理コンソールは利用していると、前と異なる点がいくつかあり、他にも数点気づいた内容についてはPRを上げました。
旧セキュリティ管理コンソールもv21.0で廃止予定ですので、新セキュリティ管理コンソールで気づいた点があれば、修正のPRを出してみてはいかがでしょうか。
Discussion
keycloak-serverのh2 dbにアクセスする方法
keycloak-uiから設定した値がDBに格納されているかどうか確認したい場合があると思います。
その場合はこちらの方法でコンソールを起動し、h2 dbのデータを確認してみてください。
jdbc:h2:file:./apps/keycloak-server/server/data/h2/keycloakdb;AUTO_SERVER=TRUEsapassword