とほほのKeycloak入門

Keycloakとは
インストール
- Docker でインストールする方法
- OpenJDK を用いてインストールする方法
チュートリアル
OIDCサンプルプログラムと連携
リンク

Keycloakとは

ID&アクセス管理を行うオープンソースです。
cloak はホテルのコート類預り所を意味します。
シングルサインオン(SSO) に対応し、OpenID Connect や SAML 2.0 の IdP(OP) として動作することができます。
ライセンスは Apache License 2.0 で商用でも無償で利用可能です。
ここでは、現時点の最新版 Keycloak 26.0 を対象として説明します。

インストール

Docker でインストールする方法

手っ取り早いのは Docker イメージを使用する方法です。

docker run -dit \
  --name my-keycloak \
  -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.0.1 start-dev

OpenJDK を用いてインストールする方法

Keycloak 26.0 は OpenJDK 21 を必要とします。下記から必要なパスを確認してダウンロードします。

$ wget https://download.oracle.com/java/21/latest/jdk-21_linux-x64_bin.tar.gz
$ tar zxvf ./jdk-21_linux-x64_bin.tar.gz
$ wget https://github.com/keycloak/keycloak/releases/download/26.0.1/keycloak-26.0.1.zip
$ unzip ./keycloak-26.0.1.zip
$ cd ./keycloak-26.0.1
$ JAVA=../jdk-21.0.5/bin/java \
  KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  ./bin/kc.sh start-dev

チュートリアル

ブラウザから http://{Keycloakのアドレス}:80880 にアクセスし、KC_BOOTSTRAP_ADMIN_USERNAME と KC_BOOTSTRAP_ADMIN_PASSWORD で指定したユーザIDとパスワードでログインします。

一時的なadminユーザを削除する

ログインすると上部に「admin は一時的な管理ユーザなので、定常的管理ユーザを作成して一時的なものは削除しなさい」とメッセージが表示されます。下記に従って定常的ユーザを作成後、一時ユーザーを削除します。

[Users]-[Add user] でユーザを作成する。
[Users]-(作成したユーザ名)-[Credentials]-[Set password] でパスワードを設定する。[Temporary] が [On] だとログイン時にパスワードの変更が求められる。
[Users]-(作成したユーザ名)-[Role mapping]-[Assign role] で [Filter by clients] を [Filter by realm roles] に変更して [admin] ロールを [Assign] する。
新しく作成した管理ユーザでログインし、問題なく操作できることを確認する。
[Users] から古い管理ユーザを選択し、[Delete user] で削除する。

自分のパスワードを変更する

右上の自分のアカウント名をクリックし、[Manage account]-[Account security]-[Signing in]-[Update] でパスワードを変更できます。

レルムを作成する

レルム(realm) は「範囲」「領域」などを意味するもので、ユーザーやグループが所属する範囲を示します。

画面左上に [Keycloak master] が表示されていなければタイトルバーの [KEYCLOAK] をクリックする。
[Keycloak master]-[Create realm] から [Realm name] にレルム名 (例: myrealm) を入力して [Create] する。

左上の選択肢で [Keycloak master] レルムや作成したレルムを切り替えることができます。

レルムにユーザを追加する

[Users]-[Create new user] から [Username] にユーザ名 (例: yamada) を入力して [Create] する。
[Credentials]-[Set password] でパスワードを設定する。

クライアントを作成する

OpenID Connect で SSO するためのクライアントを作成します。

[Client]-[Create client] から [Client ID] にクライアントID (例: myclient) を入力して [Next]。
[Client authentication] を [On] にして [Next]。
[Valid redirect URIs] に https://www.example.com/callback などのコールバックURI を入力、[Valid post logout redirect URIs] に https://www.example.com などのログアウト後のリダイレクトURI を入力して [Save]。

下記で、クライアント情報を確認します。

クライアントID(client_id) は上記の [Client ID] に入力したものになります。
クライアントシークレット(client_secret) は [Clients]-(クライアントID)-[Credentials]-[Client Secret] で確認できます。
各種エンドポイント(xxxx_endpoint) は左メニューの [Realm settings]-[Endpoints] で確認できます。

OIDCサンプルプログラムと連携

「とほほの OpenID Connect 入門」のサンプルコードと連携してみます。コンフィグ部分は下記の様に設定しました。192.168.100.1 の IPアドレスは、サンプルコードが Keycloak にアクセスできるIPアドレスに書き換えてください。client_secret も上記で確認したシークレットに変更してください。

config = {
  "type": "keycloak",
  "issuer": "http://192.168.100.1:8080/realms/myrealm",
  "port": 443,
  "scope": "openid profile email",
  "client_id": "myclient",
  "client_secret": "pGCZA6ELpE7rc********************",
  "redirect_uri": "https://www.example.com/callback",
  "authorization_endpoint": "http://192.168.100.1:8080/realms/myrealm/protocol/openid-connect/auth",
  "token_endpoint": "http://192.168.100.1:8080/realms/myrealm/protocol/openid-connect/token",
  "end_session_endpoint": "http://192.168.100.1:8080/realms/myrealm/protocol/openid-connect/logout",
  "revocation_endpoint": "http://192.168.100.1:8080/realms/myrealm/protocol/openid-connect/revoke",
  "jwks_uri": "http://192.168.100.1:8080/realms/myrealm/protocol/openid-connect/certs",
  "logout_uri": "https://www.example.com",
  "exclude_urls": [ "/", "/login", "/callback" ],
}

あとはサンプルコードの説明に従い動かしてみてください。

リンク

Keycloak Official Site

初版:2024年10月20日最終更新:2024年10月20日

https://www.tohoho-web.com/ex/keycloak.html