はじめに

現在、KeycloakのSPIについて調査と実験をしています。macOSでKeycloakのIDE開発環境を構築した時に、いくつかつまずいたポイントがありました。そこで、必要コンポーネントのインストールから、IDEでデバックするところまでの情報をまとめてみました。

構築環境は、Apple silicon搭載のマシンで構築しています。アーキテクチャに依存しない構築手順を選んだつもりですが、Intel macでの動作検証ができていないため、x86_64系のmacでは別の問題が発生するかもしれません。

Keycloak（キークローク）は、Javaで記述された、SSOやID管理を提供するオープンソースソフトウェア製品です。本掲載内容は、Building from sourceを参考に構築しています。Keycloakは更新頻度が高いので、問題発生時は、keycloakリポジトリ内の情報を確認することをお勧めします。

構築環境

記事の投稿現在、Keycloak(ver21.1.1)、IDEはEclipse 2023の環境で構築しました。主な構成要素は以下となります。

主構成

Keycloak ver21.1.1
Eclipse 2023 Version: 2023-03 (4.27.0) Build id: 20230309-1520

マシンスペック

macOS ：Ventura 13.4
cpu:Apple M1 pro
memory:16G

必須コンポーネント

Homebrew 4.0.21
JDK17 "17.0.7" 2023-04-18 LTS
maven 3.9.2
gsed 4.9
git 2.39.2 (Apple Git-143)

事前準備

該当のコンポーネントが既にインストールされている場合は、インストール作業は不要です。

Homebrewのインストール

Homebrewのインストールとバージョン確認

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
…(中略)
$ brew -v
Homebrew 4.0.22
Homebrew/homebrew-core (git revision bc18192d5f0; last commit 2023-02-24)
Homebrew/homebrew-cask (git revision c24db49e94; last commit 2023-02-24)

Homebrewの詳細はこちらをご参照ください。

OpenJDK 17のインストール

OpenJDK 17のインストールとバージョンの確認
```
$ brew install openJDK@17
$ sudo ln -sfn /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk
```
Keycloakリポジトリのドキュメントには、Building from sourceより、Ensure you have JDK 11 (or newer),と記載されていたので、当初、OpenJDK 20での構築を試みました。しかし、Mavenビルド中のエラーが解決できなかったため、OpenJDK 17を採用しています。(OpenJDK 11での動作は確認済みですが、より最新に近いOpenJDK 17で動作検証を行いました。)
~/.zshrcの編集
~/.zshrcをvimや、適当なエディターでJAVA_HOMEをOpenJDK 17にexportします。
```
export JAVA_HOME=`/usr/libexec/java_home -v "17"`
PATH=$JAVA_HOME/bin:$PATH
```

OpenJDK 17に切り替える

.zshrcをシステムに反映し、javaのバージョンを確認します。

$ source ~/.zshrc
$ javac -version
javac 17.0.7
$ java -version
java version "17.0.7" 2023-04-18 LTS
Java(TM) SE Runtime Environment (build 17.0.7+8-LTS-224)
Java HotSpot(TM) 64-Bit Server VM (build 17.0.7+8-LTS-224, mixed mode, sharing)

mavenのインストール

mavenのインストールとバージョンの確認

$ brew install maven
$ mvn -version
Apache Maven 3.9.2 (c9616018c7a021c1c39be70fb2843d6f5f9b8a1c)
Maven home: /opt/homebrew/Cellar/maven/3.9.2/libexec
Java version: 17.0.7, vendor: Oracle Corporation, runtime: /Library/Java/JavaVirtualMachines/JDK-17.JDK/Contents/Home
Default locale: ja_JP, platform encoding: UTF-8
OS name: "mac os x", version: "13.4", arch: "aarch64", family: "mac"

jbossリポジトリの追加
~/.m2/settings.xmlをvimや、適当なエディターで編集し、jboss-public-repository-groupのrepositoryの定義を追加します。

…(中略)
  <mirrors>
…(中略)
    <mirror>
    <id>jboss-public-repository-group-https</id>
    <mirrorOf>jboss-public-repository-group</mirrorOf>
    <name>Jboss public https</name>
    <url>https://repository.jboss.org/nexus/content/groups/public/</url>
  </mirror>
</mirrors>
…(中略)

gsedのインストール

gsedのインストールとバージョンの確認
```
$ brew install gnu-sed
$ gsed --version
gsed (GNU sed) 4.9
Copyright (C) 2022 Free Software Foundation, Inc.
 …(中略)
```
Keycloakのビルドスクリプト内には、sedコマンドをコールする処理が記述されています。gnu-sed仕様の動作が前提なので、macOSではgnu-sedを別途インストールする必要があります。

gitのインストール

gitのインストールとバージョンの確認

$ brew install git
$ git --version
git version 2.39.2 (Apple Git-143)

Keycloakビルド環境の構築

Keycloakの構築環境を整備します。今回の例では、~/keycloak_workspaceフォルダとしていますが、それぞれの環境に応じて作業してください。

Keycloakのクローン

下記コマンドを実行し、Keycloakをクローンします。クローンが完了すると、~/keycloak_workspace/keycloakフォルダが作成されます。
```
$ mkdir ~/keycloak_workspace
$ cd ~/keycloak_workspace
$ git clone https://github.com/keycloak/keycloak.git
```

Keycloakのビルド

~/keycloak_workspace/keycloakフォルダで、実行に必要なモジュールをビルドします。この時、ビルド後のモジュールテストでエラー終了してしまうため、skipTestsオプションを指定して、テストをスキップします。mvn clean install実行後は、[INFO] BUILD SUCCESSが出力されていることを確認します。
```
$ cd ~/keycloak_workspace/keycloak
$ mvn clean install -DskipTests=true
…(中略)
[INFO] BUILD SUCCESS

$ cd distribution
$ mvn clean install
…(中略)
[INFO] BUILD SUCCESS
```

ビルドしたKeycloakの動作確認

ビルドしたKeycloakの動作を確認します。正しく起動すると、コンソールにStarted Keycloak (http://localhost:8081/auth) in XXXX msのメッセージが表示されます。

$ cd ~/keycloak_workspace/keycloak
$ mvn -f testsuite/utils/pom.xml exec:java -Pkeycloak-server
[INFO] Scanning for projects...
[INFO] 
[INFO] ---------------< org.keycloak:keycloak-testsuite-utils >----------------
[INFO] Building Keycloak TestSuite Utils 999.0.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- exec:3.0.0:java (default-cli) @ keycloak-testsuite-utils ---
…(中略)
Started Keycloak (http://localhost:8081/auth) in XXXX ms

WebブラウザのURL欄にhttp://localhost:8081/authを入力し起動を確認します。

IDE環境の設定

Pleiades All in One Eclipseのインストール

Pleiades All in One Eclipseのダウンロードリンクより、Mac > Javaをクリックして、インストーラーをダウンロードします。
ダウンロード後、pleiades-2023-03-java-mac-jre_20230326.dmgをダブルクリックして、
pleiades_2023_03アイコンを、アプリケーションにドラッグ&ドロップします。

ワークスペースの指定

アプリケーションフォルダより、pleiades_2023_03をダブルクリックして、Eclipseを起動します。
Keycloakビルド環境の構築で作成した、~/keycloak_workspaceをワークスペースに指定して、[起動]ボタンをクリックします。

KeycloakのMavenプロジェクトのインポート

Keycloakのクローンで生成したkeycloakプロジェクトを、keycloak_workspaceへインポートします。パッケージエクスプローラを右クリックして、[インポート…]メニューを選択します。[Maven] > [既存 Maven プロジェクト]を選択し、[次へ>]ボタンをクリックします。
keycloakフォルダを選択し、[Open]ボタンをクリックします。
keycloakフォルダの/pom.xmlファイルにチェックして、[完了]ボタンをクリックします。
インポートが正常に完了すると、パッケージエクスプローラーが以下の状態となります。

Keycloakのデバッグ起動の設定

Eclipse ツールバー・ボタン > [デバッグ▼]をクリックし、[デバッグの構成…]メニューを選択します。

デバッグ構成画面より、Mavenビルドを右クリックし、[新規構成]メニューを選択します。
[メイン]タブを選択し、下記の項目を設定します。
- 名前(任意)：
```
KeycloakServer
```
- 基底ディレクトリ：
```
${workspace_loc:/keycloak}
```
  ※直接入力するか、[ワークスペース…]ボタンをクリックしてkeycloakディレクトリを選択します。
- ゴール：
```
-f testsuite/utils/pom.xml exec:java -Pkeycloak-server
```
[JRE]タブを選択し、下記の項目を設定します。
- VM引数:
```
-Dkeycloak.connectionsJpa.url=jdbc:h2:./keycloak;AUTO_SERVER=TRUE -Dmaven.surefire.debug=true`
```
設定後、[適用]ボタンをクリックします。

Keycloak起動確認

[デバッグ]ボタンをクリックしてKeycloakをデバッグ起動します。
コンソールでStarted Keycloak (http://localhost:8081/auth) in XXXXX msの表示を確認します。
WebブラウザのURL欄にhttp://localhost:8081/authを入力し起動を確認します。

[Administration Console]のリンクをクリックしてログイン画面に遷移します。
Usernameにadmin、Passwordにadminを入力し、管理コンソールにログインします。

ブレークポイントの動作確認

ビルドしたKeycloakの動作を確認します。パッケージエクスプローラーより、testsuite/utils/src/main/java/org/keycloak/testsuite/KeycloakServer.javaを選択し、394行目のstart()メソッドにブレークポイントを設定します。
前述の[#Keycloakのデバッグ起動の設定]で構成した、KeycloakServerの[ソース]タブ内のソース・ルックアップ・パス：に、/keycloak/testsuite/util/srcを追加します。
- ソースの追加
  1. [追加…]ボタンをクリックします。
  2. ワークスペース・フォルダーを選択します。
  3. [追加…]ボタンをクリックします。
  4. Keycloak > testsuite > srcを選択します。
  5. [OK]ボタンクリックします。
Eclipse ツールバー・ボタン > [デバッグ▼]をクリックし、[KeycloakServer]メニューを選択して実行します。
Keycloakが起動され、目的のブレークポイントで停止したことを確認します。

これで無事、IDEによる快適なデバッグ環境が構築できました。

まとめ

最後まで読んでいただき、ありがとうございました。今回、Keycloakの開発環境を構築し、多機能で拡張性に優れたアプリケーションだと実感しました。引き続きAuthentication SPIについて調査する予定なので、Keycloakをシリーズ化できればと考えております。この情報が皆様のお力になれれば幸いです。

リンク