ITブログ

Windows+Keycloak23

サーバー 2024.01.02

Windows系OSにKeycloakをセットアップする手順。

Windows系OSにOpenIDConnectに対応したIAM(ID管理・アクセス管理)システムであるKeycloak v23系をインストールする手順です。
運用系の構築のヒントとしてPostgreSQL対応およびSSL対応と、23系の言語不具合修正も含めて解説します。
以下の順番で進めます。
 
1. Javaインストール
2. Keycloakインストール
3. PostgreSQLインストール
4. 自己証明書作成
5. keycloak.conf設定
6. admin言語リソース修正
 
※自己証明書を作成するために、WSLとOpenSSLがインストールされている必要があります。
　（外部Linuxサーバーが使用できる場合は、そちらで作成したファイルを使用しても構いません。）
 
1. Javaインストール
Windows11にJava(JDK)21をインストールする手順は以下です。
パス環境変数も設定する必要があります。
 
 
※Keycoak v23未満をインストールする場合はJDK21未満をインストールする必要があります。
 
2. Keycloakインストール
Keycloak23をダウンロードします。
 
06_keycloak.png
 
ダウンロードしたZIPファイルを解凍してできた "keycloak-23.0.3" フォルダを任意のパスに移動します。
ここでは、c:\Files\keycloak-23.0.3 に配置します。
※他のパスに配置する場合は、以降のパスを読み替えてください。
 
Keycloakの起動を確認します。
コマンドプロンプトで以下のコマンドを実行します。
 
cd c:\Files\keycloak-23.0.3
bin\kc.bat start-dev
 
コマンドプロンプトにいくつかログが出力されます。その中に以下のような行が含まれていればポート8080でKeycloakが起動できています。
2024-01-02 18:41:14,262 INFO  [io.quarkus] (main) Keycloak 23.0.3 on JVM (powered by Quarkus 3.2.9.Final) started in 11.333s. Listening on: http://0.0.0.0:8080
 
ブラウザで http://localhost:8080 にアクセスするとKeycloakが起動していることがわかります。
07_keycloak.png
 
このあとPostgreSQLとSSLの設定をするので、一度Keycloakを終了します。
コマンドプロンプトでCtrl+Cキーを押すと終了できます。
 
3. PostgreSQLインストール
Keycloakは標準でH2 Database（インメモリ）で動作します。
運用系はもちろん、開発系でもデータ保持ができる外部データベースに対応させたほうが便利です。
 
JDBCドライバ経由で接続できるデータベースであればKeycloakから接続可能です。
テスト済みのデータベースは下記に記載されています。
 
01_pg.png
 
ここではPostgreSQL16をインストールしてKeycloak23から接続します。
以下からダウンロードします。
 
02_pg.png
 
ダウンロードしたインストーラでPostgreSQL16をインストールします。
インストーラによるインストールの途中でスーパーユーザー(postgres)のパスワードを設定する必要があります。
スーパーユーザーのパスワードには推測困難なパスワードを設定しましょう。
03_pg.png
 
PostgreSQLがインストールできたら、Keycloakから接続・セットアップできるように設定します。
コマンドプロンプトを起動して以下のコマンドと、インストール時に設定したスーパーユーザー(postgres)のパスワードを入力します。
 
"C:\Program Files\PostgreSQL\16\bin\psql" -U postgres
 
04_pg.png
 
スーパーユーザーでPostgreSQLにログインできたら、以下のコマンドでKeycloak用のオブジェクトを作成します。
 
create database mykeycloakdb;
create role mykeycloakuser with login password 'mykeycloakuserspassword';
grant all on database mykeycloakdb to mykeycloakuser;
\c mykeycloakdb
create schema keycloak authorization mykeycloakuser;
 
05_pg.png
 
コマンドの実行が終わったら "\q" でpsqlコマンドを終了します。
上記のPostgreSQLのコマンドで行っている内容は以下になります。
 
・データベース作成 / create database
　　名前はmykeycloakdbとしています。何でも良いです。
 
・ユーザー作成 / create role
　　名前はmykeycloauserとしています。
　　パスワードはmykeycloakuserpasswordとしています。
　　名前、パスワードどちらも何でも良いです。
 
・作成したデータベースの全権限を作成したユーザーに付与 / grant
 
・ログイン先データベースを作成したデータベースに切り替え / \c (データベース名)
 
・作成したデータベースに、スキーマを作成 / create schema
　　名前はkeycloakとしています。何でも良いです。
　　同時に作成したユーザーに権限を付与しています。
 
Keycloakで使用するデータベースの準備ができました。
KeycloakをこのPostgreSQLに接続して起動してみます。コマンドプロンプトで以下のコマンドを実行してください。
 
cd c:\Files\keycloak-23.0.3
bin\kc.bat start-dev --db postgres --db-url "jdbc:postgresql://localhost/mykeycloakdb" --db-username mykeycloakuser --db-password mykeycloakuserspassword --db-schema keycloak
 
指定できるパラメータは下記に記載されています。
 
08_pg.png
 
"2. Keycloakインストール" の確認と同じように、ポート8080で起動したログが表示されたら、ブラウザで http://localhost:8080 にアクセスして確認します。
データが永続化されることを確認しましょう。ウェルカム画面で管理者ユーザーを作成します。
管理者ユーザーが作成出来たら "Administration Console >" をクリックしてログインできることを確認します。
 
09_keycloak.png
10_keycloak.png
 
管理者ユーザーの作成が確認出来たら、一度Keycloakを終了します。
コマンドプロンプトでCtrl+Cキーを押すと終了できます。
もう一度Keycloakを起動して、作成した管理者ユーザーでログインできればPostgreSQLへ永続化できていることが確認できます。
 
cd c:\Files\keycloak-23.0.3
bin\kc.bat start-dev --db postgres --db-url "jdbc:postgresql://localhost/mykeycloakdb" --db-username mykeycloakuser --db-password mykeycloakuserspassword --db-schema keycloak
 
ポート8080で起動したログが表示されたら、ブラウザで http://localhost:8080 にアクセスして確認します。
ウェルカム画面の表示が初回起動時とは異なり、"Administration Console" の領域で管理者ユーザーを登録するフォームが表示されていません。
"Administration Console >" をクリックするとログイン画面に遷移します。
 
11_keycloak.png
12_keycloak.png
13_keycloak.png
 
作成した管理者ユーザーでログインできることを確認したら、一度Keycloakを終了します。
コマンドプロンプトでCtrl+Cキーを押すと終了できます。
 
4. 自己証明書作成
Keycloakを運用系で使用する場合はSSL(HTTPS)が必須です。開発系でも運用系との差分をなるべくなくすためにSSLしておくべきでしょう。
まずは自己証明書を作成する手順を説明します。
 
コマンドプロンプトで "wsl" と入力し、WSL(Linux)を開始します。
"cd /mnt/c/Files/keycloak-23.0.3/conf" でKeycloakのconfディレクトリに移動してください。
 
秘密鍵、署名要求(CSR)、サーバー証明書の順でファイルを作成します。
※署名要求(CSR)の内容は例です。Common Name(ドメイン)以外は自由に設定してください。
 
openssl genrsa 2048 > server.key.pem
openssl req -new -key server.key.pem > server.csr
--
Country Name            : JP
State or Province Name    : Hokkaido
Locality Name            : Ebetsu
Organization Name        : miu-soft
Organization Unit Name    : 
Common Name                : localhost
Email Address            : 
A challenge password    : 
An optional company name: 
--
openssl x509 -req -days 3650 -signkey server.key.pem < server.csr > server.crt.pem
 
上記コマンドで、c:\Files\keycloak-23.0.3\conf フォルダに以下の３ファイルが作成されます。
 
server.key.pem
server.csr
server.crt.pem
 
5. keycloak.conf設定
作成した自己証明書をKeycloakに設定してSSL(HTTPS)通信できるようにします。
また、起動時コマンドで指定していたデータベース関連のパラメータも設定ファイルに記載してコマンドをシンプルにします。
c:\Files\keycloak-23.0.3\conf\keycloak.conf ファイルをテキストエディタで開きます。
 
# Basic settings for running in production. Change accordingly before deploying the server.
 
# Database
 
# The database vendor.
db=postgres
 
# The username of the database user.
db-username=mykeycloakuser
 
# The password of the database user.
db-password=mykeycloakuserspassword
 
# The full database JDBC URL. If not provided, a default URL is set based on the selected database vendor.
db-url=jdbc:postgresql://localhost/mykeycloakdb
 
# The database schema.
db-schema=keycloak
 
# Observability
 
# If the server should expose healthcheck endpoints.
#health-enabled=true
 
# If the server should expose metrics endpoints.
#metrics-enabled=true
 
# HTTP
 
# The file path to a server certificate or certificate chain in PEM format.
#https-certificate-file=${kc.home.dir}conf/server.crt.pem
https-certificate-file=c:/Files/keycloak-23.0.3/conf/server.crt.pem
 
# The file path to a private key in PEM format.
https-certificate-key-file=c:/Files/keycloak-23.0.3/conf/server.key.pem
 
# The proxy address forwarding mode if the server is behind a reverse proxy.
#proxy=reencrypt
 
# Do not attach route to cookies and rely on the session affinity capabilities from reverse proxy
#spi-sticky-session-encoder-infinispan-should-attach-route=false
 
# Hostname for the Keycloak server.
hostname=localhost
 
http-port=80
https-port=443
 
変更箇所を強調表示しています。
修正したkeycloak.confを保存した後、再度Keycloakを起動します。
データベース関連のパラメータを設定ファイルに記載したので、起動コマンドはシンプルになりました。
 
cd c:\Files\keycloak-23.0.3
bin\kc.bat start-dev
 
HTTPおよびHTTPSのポートも設定ファイルで指定したので、起動時のログには以下のように出力されます。
 
2024-01-02 21:04:55,105 INFO  [io.quarkus] (main) Keycloak 23.0.3 on JVM (powered by Quarkus 3.2.9.Final) started in 4.515s. Listening on: http://0.0.0.0:80 and https://0.0.0.0:443
 
ブラウザで https://localhost にアクセスしてHTTPS通信ができることを確認します。
 
14_keycloak.png
 
運用モードでの起動も確認しましょう。今までは kc.bat の引数で "start-dev" を指定していました。
これは開発モードでの起動方法になります。
 
運用モードで起動するには、まず "build" をする必要があります。
build後に、"start" を指定してKeycloakを起動します。
 
cd c:\Files\keycloak-23.0.3
bin\kc.bat build
bin\kc.bat start
 
開発モードではHTTPでも起動できましたが、運用モードでは強制的にHTTPSのみの起動となります。
起動時のログには以下のように出力されます。
 
2024-01-02 21:13:31,422 INFO  [io.quarkus] (main) Keycloak 23.0.3 on JVM (powered by Quarkus 3.2.9.Final) started in 6.819s. Listening on: https://0.0.0.0:443
 
ブラウザで https://localhost にアクセスしてHTTPS通信ができることを確認します。
 
14_keycloak.png
 
6. admin言語リソース修正
Keycloakはデフォルトでは英語で表示されますが、多言語を有効にすると日本語等で画面を表示することができます。
管理者でadminにログインした後、左メニューから "Realm settings" を選択、"Localization" タブを選択します。
"Intarnationalization" を "Enabled" にした後、"Supported locales" で "日本語" を追加します。
※レルムごとに設定できます。
 
15_keycloak.png
 
デフォルトを日本語に変更する場合は、"Default locale" で "日本語" を選択します。
最後に "Save" ボタンを押すと設定が反映されます。
 
16_keycloak.png
 
ブラウザの更新ボタン(F5)を押すと日本語表示に切り替わります。
 
17_keycloak.png
 
日本語になることは確認できましたが、赤枠の部分（英語だと"Groups"）に不具合がありました。
v22.0.2までは "Groups" と表示されていました。
 
v22.0.2 日本語表示
18_keycloak_v22.0.2..png
 
v23.0.0から、メッセージリソースの groups に、groupsHelpの文言が設定されてしまったようです。
元のリソースを直接修正するとバージョン更新時に影響がありそうなので、カスタマイズポイントである "テーマ(Theme)" で対応してみます。
 
テーマによるカスタマイズ方法は下記に記載されています。
 
 
19_keycloak.png
 
流れは以下です。
1. 既存のテーマを拡張した mytheme を作成する
2. 管理者画面で admin を mytheme に切り替える
 
1. 既存のテーマを拡張した mytheme を作成する
c:\Files\keycloak-23.0.3\theme フォルダに、サブフォルダと2つのファイルを作成します。
 
20_keycloak.png
 
テーマ名 "mytheme" は何でも良いです。
theme.properties の内容は以下です。
 
parent=keycloak.v2
 
"parent" では この新しいテーマが、どのテーマのadminタイプを継承するかを指定します。
adminタイプはデフォルトでは "keycloak.v2" しかないため、keycloak.v2 を指定します。
 
21_keycloak.png
 
messages_ja.properties の内容は以下です。
間違っているgroupsキーの文言に、"グループ" を指定します。文字エンコーディング方式は UTF-8 です。
 
groups=グループ
 
2. 管理者画面で admin を mytheme に切り替える
管理画面に管理者ユーザーでログインして、追加したテーマに切り替えます。
 
ログインしたら、左メニューから "レルムの設定" を選択、"テーマ" タブを選択します。
"管理コンソールテーマ" で "mytheme" を選択した後、"保存" ボタンを押してください。
 
22_keycloak.png
 
Keycloakを起動して修正を確認します。Keycloakが起動中の場合は一度停止してください。
 
cd c:\Files\keycloak-23.0.3
bin\kc.bat start
 
管理画面に管理者ユーザーでログインして、メニューの groups が "グループ" に修正されたことを確認できます。
本来のgroupsHelpキーの文言も "グループ" に変わってしまいますが、メニューに長いヘルプ文言が表示されるよりは良いかと思います。
 
23_keycloak.png
 
 
以上でWindows系OSにKeycloakをインストールして、PostgreSQLによる永続化に対応し、SSL通信を有効にできました。
また、管理画面を日本語表示に切り替え、簡単なバグをテーマ機能の上書きにより修正する方法を説明してきました。
 
KeycloakはOpenIDConnect、OAuth2をカバーし、WebAuthnやワンタイムパスワードにも対応する非常に高機能なIAM(ID and Access Management)となっています。
今後、医療系ITシステムでも認証・認可基盤として重要なソフトウェアになると思います。
 
≪ Windows+Java(JDK21)環境構築