これは、なにをしたくて書いたもの？
Keycloak 17.0.0.から、KeycloakはQuarkusベースになりました。ちょっと気になっていたので、そろそろ触ってみたいと思います。
QuarkusベースになったKeycloak
先に書いた通り、Keycloakは17.0.0からQuarkusベースとなり、これまでのWildFlyベースのディストリビューションは非推奨になりました。
The default Keycloak distribution is now based on Quarkus.
The WildFly distribution of Keycloak is now deprecated, with support ending June 2022.
Keycloak 17.0.0 released - Keycloak
以前からKeycloak.Xとして時々名前が出ていたなぁと思っていましたが、こちらが本流になりました、と。
Introducing Keycloak.X - Keycloak
Introducing Keycloak.X Distribution - Keycloak
WildFlyベースのディストリビューションのサポートは、2022年6月に終了（もう過ぎていますが…）で、Keycloak 17.0.0のリリースが
2022年2月なのでけっこうなスピードですね。
Webサイトの構成も変わっていて、「Guides」と「Docs」がありますが、基本的にGuidesを見ることになりそうですね。Docsの方に
残っているドキュメントもありますが。
また、Quarkusとは関係ないですが、Keycloak 17.0.0リリースの段階で各種クライアントアダプターも非推奨になったようです。
Deprecation of Keycloak adapters - Keycloak
こちらはメジャー・マイナーリリース終了が2022年9月、マイクロリリース終了が2022年12月となっています。
使用できるデータベースとしては、PostgreSQLやCockroachDB等のPostgreSQL互換のデータベースを残し、それ以外のデータベース
（MySQL、MariaDB、SQL Server、Oracle Database）のサポートは段階的に廃止していくようです。
Supported databases for the new Keycloak store - Keycloak
このあたりはちょっと注意ですね。
とりあえず、今回はあまり深く考えずにKeycloakを触ってみたいと思います。
環境
今回の環境は、こちらです。
Ubuntu Linux 20.04 LTS。
$ uname -srmvpio Linux 5.4.0-124-generic #140-Ubuntu SMP Thu Aug 4 02:23:37 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux $ lsb_release -a No LSB modules are available. Distributor ID: Ubuntu Description: Ubuntu 20.04.4 LTS Release: 20.04 Codename: focal
OpenJDKのバージョンは、17とします。
$ java --version openjdk 17.0.4 2022-07-19 OpenJDK Runtime Environment (build 17.0.4+8-Ubuntu-120.04) OpenJDK 64-Bit Server VM (build 17.0.4+8-Ubuntu-120.04, mixed mode, sharing)
Keycloakをインストールして、管理ユーザーでログインする
Keycloakのインストール方法は、zipアーカイブ、コンテナイメージ、Kubernetes Operatorから選ぶことができます。
今回は、zipアーカイブを選択します。
ガイドとしては、こちらに沿って進めることになります。
アーカイブをダウンロード。
$ curl -LO https://github.com/keycloak/keycloak/releases/download/19.0.1/keycloak-19.0.1.zip
展開して
$ unzip keycloak-19.0.1.zip
ディレクトリ内へ移動。
$ cd keycloak-19.0.1
ドキュメントを見ると、bin/kc.shというスクリプトでstart-devというコマンドで起動するみたいです。
とりあえず、起動してみましょう。
bin/kc.sh start-dev
起動時に、なにか設定をしていそうなログが出力されています。
Updating the configuration and installing your custom providers, if any. Please wait.
8080ポートをリッスンして起動するようです。
2022-08-14 19:07:27,082 INFO [io.quarkus] (main) Keycloak 19.0.1 on JVM (powered by Quarkus 2.7.6.Final) started in 8.905s. Listening on: http://0.0.0.0:8080
Quarkusのバージョンは、2.7.6.Finalですね。また、有効化されているExtensionもリストアップされます。
2022-08-14 19:07:27,090 INFO [io.quarkus] (main) Installed features: [agroal, cdi, hibernate-orm, jdbc-h2, jdbc-mariadb, jdbc-mssql, jdbc-mysql, jdbc-oracle, jdbc-postgresql, keycloak, logging-gelf, narayana-jta, reactive-routes, resteasy, resteasy-jackson, smallrye-context-propagation, smallrye-health, smallrye-metrics, vault, vertx]
http://localhost:8080にアクセスしてみます。
こんなコンソールが表示されました。
最初に管理ユーザーを作成しなさい、ということみたいなので
OpenJDK / Create an admin user
作ってみます。
表示されている「Administration Console」というリンクをクリックして、先ほど作成した管理ユーザーのユーザー名とパスワードを入力して
ログイン。
ログインできました。
Realmとユーザーを作成する
次は、Realmとユーザーを作る手順になっています。
こちらに沿って進めてみましょう。
Realmは、Keycloakのテナントに相当するものだそうです。アプリケーションやユーザーに対する、Keycloak内での管理単位ですね。
A realm in Keycloak is the equivalent of a tenant. It allows creating isolated groups of applications and users.
デフォルトではmasterというRealmがあるようですが、これはKeycloakの管理用Realmであり、Keycloakの利用者が作成するアプリケーション
などで使用するものではないようです。
By default there is a single realm in Keycloak called master. This is dedicated to manage Keycloak and should not be used for your own applications.
実際、この状態で表示されているRealmはmasterとなっています。
Realmが表示されている箇所を選ぶと、「Create Realm」というボタンが表示されるのでこちらを選び
今回はdemoというRealmを作成してみます。
作成すると、demo Realmに移ります。
次に、ユーザーを作成してみましょう。左メニューの「Users」を選択して
適当に情報を入力して、ユーザーを作成。
できました。
パスワードを設定しないとログインできないみたいなので「Credentials」を選択して、「Set password」を押します。
パスワードを設定。「Temporary」をOn（デフォルト）にしておくと初回ログイン時にパスワードの変更を求められますが、今回はOffに
しておきます。
これで、保存。
管理ユーザーは、1度サインアウトします。
ログアウト後のURLはhttp://localhost:8080/realms/master/protocol/openid-connect/auth?client_id=...みたいになっているのですが、
http://localhost:8080/realms/[Realm名]/accountがアカウントコンソールと呼ばれるものらしいので、こちらにアクセスしてみます。
今回の場合は、http://localhost:8080/realms/demo/accountになりますね。アクセスすると、こんな表示になりました。
ヘッダーにある「Sign in」をクリックして、ログイン。
ログインできました。
とりあえず、今回はこのくらいの操作にしておきましょう。
あとは、この時点で少し気になることを調べておきます。
start-devコマンドとは？
Keycloakの起動時にstart-devというコマンドを使いました。明らかに開発モードのようなコマンドですが、こちらはどういう意味に
なるのでしょう？
こちらに説明がありました。Keycloakには2つの起動モードがあるようです。
Configuring Keycloak / Starting Keycloak
やはり、start-devというのはKeycloakを開発モードで起動するように指示するようです。
Configuring Keycloak / Starting Keycloak / Starting Keycloak in development mode
開発モードはKeycloakを初めて試してみる人、すぐに起動したい人を対象にしています。開発者にとって便利なデフォルト設定になっています。
開発モードでは、以下の状態となるそうです。
- HTTPが有効
- 厳密なホスト名解決が無効
- ローカルキャッシュのみの利用（高可用性向けの分散キャッシュは使わない）
- テーマおよびテンプレートのキャッシュが無効化される
もうひとつのモードは、プロダクションモードです。
Configuring Keycloak / Starting Keycloak / Starting Keycloak in production mode
こちらはstartコマンドで起動しますが、設定していない状態だとエラーになります。
$ bin/kc.sh start ERROR: Failed to run 'start' command. ERROR: You can not 'start' the server in development mode. Please re-build the server first, using 'kc.sh build' for the default production mode. For more details run the same command passing the '--verbose' option. Also you can use '--help' to see the details about the usage of the particular command.
kc.sh buildでプロダクション環境向けに設定を行う必要があるようです。
そのあたりのガイドは、こちらですね。
Configuring Keycloak for production - Keycloak
今回はこの点はちょっと置いておいて、続きを見ていきます。
プロダクションモードでは、以下がデフォルトになります。
このあたりを設定するためのガイドが、上記のページだということですね。
管理ユーザーをWebコンソール以外から作成したい
管理ユーザーはWebコンソールから作成しましたが、これをCLIで作成できたらなと思うものです。
こちらに記載がありました。
Configuring Keycloak / Setup of the initial admin user
初回起動時に以下の環境変数を指定することで、管理ユーザーを作成できるようです。
KEYCLOAK_ADMIN… 管理ユーザーのユーザー名KEYCLOAK_ADMIN_PASSWORD… 管理ユーザーのパスワード
また、初期の管理者権限を持つユーザーがすでに存在している場合はこれらの環境変数を設定しているとエラーになるようです。
試してみましょう。
Keycloakをクリーンインストールした状態で
$ unzip keycloak-19.0.1.zip $ cd keycloak-19.0.1
KEYCLOAK_ADMINおよびKEYCLOAK_ADMIN_PASSWORD環境変数を指定して起動。
$ KEYCLOAK_ADMIN=admin KEYCLOAK_ADMIN_PASSWORD=password bin/kc.sh start-dev
起動時のログに、指定したユーザーがmaster Realmに追加されたことが出力されました。
2022-08-14 20:07:14,921 INFO [org.keycloak.services] (main) KC-SERVICES0009: Added user 'admin' to realm 'master'
この状態で、環境変数で指定した管理ユーザーでログインできます。
以降は、環境変数の指定は不要になりますが
$ bin/kc.sh start-dev
もう1度同じ環境変数を指定して起動すると
$ KEYCLOAK_ADMIN=admin KEYCLOAK_ADMIN_PASSWORD=password bin/kc.sh start-dev
エラーは出力されますが、起動に失敗するようなことはありません。これはドキュメント通りの挙動ですね。
2022-08-14 20:11:27,812 ERROR [org.keycloak.services] (main) KC-SERVICES0010: Failed to add user 'admin' to realm 'master': user with username exists
では、ユーザー名を変えるとどうなるでしょう。
$ KEYCLOAK_ADMIN=admin2 KEYCLOAK_ADMIN_PASSWORD=password2 bin/kc.sh start-dev
これはダメなようです。
2022-08-14 20:13:28,132 ERROR [org.keycloak.services] (main) KC-SERVICES0010: Failed to add user 'admin2' to realm 'master': user with username exists
この環境変数で作成可能なのは、あくまでmaster Realmに対する最初の管理ユーザーのようですね。
管理ユーザーを作成した後は、kcadmというスクリプトで操作できるようですが、それはまた今度。
まとめ
QuarkusベースになったKeycloakを触ってみました。Web UIはそうでもないですけど、構成やスクリプトまわりは相当変わっている気がしますね。
まだOpenID Connectなどは扱っていないので、そのあたりは徐々に進めていきましょう。
