快適！ Keycloak Develop Life - macOS + Eclipse 2023 -

# はじめに

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

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

> [**Keycloak**（キークローク）](https://ja.wikipedia.org/wiki/Keycloak "Keycloak wiki")は、Javaで記述された、SSOやID管理を提供するオープンソースソフトウェア製品です。本掲載内容は、[**Building from source**](https://github.com/keycloak/keycloak/blob/main/docs/building.md "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のインストールとバージョン確認**
  
  ```shell-session
  $ /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の詳細は[こちら](https://brew.sh/index_ja)をご参照ください。

## OpenJDK 17のインストール

1. **OpenJDK 17のインストールとバージョンの確認**
   
   ```shell-session
   $ 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**](https://github.com/keycloak/keycloak/blob/main/docs/building.md "Building from source")より、`Ensure you have JDK 11 (or newer),`と記載されていたので、当初、OpenJDK 20での構築を試みました。しかし、Mavenビルド中のエラーが解決できなかったため、OpenJDK 17を採用しています。(OpenJDK 11での動作は確認済みですが、より最新に近いOpenJDK 17で動作検証を行いました。)

2. **`~/.zshrc`の編集**
   ~/.zshrcをvimや、適当なエディターでJAVA_HOMEをOpenJDK 17にexportします。
   
   ```
   export JAVA_HOME=`/usr/libexec/java_home -v "17"`
   PATH=$JAVA_HOME/bin:$PATH
   ```

3. **OpenJDK 17に切り替える**
   
   .zshrcをシステムに反映し、javaのバージョンを確認します。
   
   ```shell-session
   $ 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のインストール

1. **mavenのインストールとバージョンの確認**
   
   ```shell-session
   $ 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"
   ```

2. **jbossリポジトリの追加**
   ~/.m2/settings.xmlをvimや、適当なエディターで編集し、jboss-public-repository-groupのrepositoryの定義を追加します。
   
   ```xml-doc
   …(中略)
     <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のインストールとバージョンの確認**
  
  ```shell-session
  $ 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のインストールとバージョンの確認**
  
  ```shell-session
  $ brew install git
  $ git --version
  git version 2.39.2 (Apple Git-143)
  ```

# Keycloakビルド環境の構築

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

## Keycloakのクローン

- 下記コマンドを実行し、Keycloakをクローンします。クローンが完了すると、~/keycloak_workspace/keycloakフォルダが作成されます。
  
  ```shell-session
  $ 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`が出力されていることを確認します。
  
  ```shell-session
  $ cd ~/keycloak_workspace/keycloak
  $ mvn clean install -DskipTests=true
  …(中略)
  [INFO] BUILD SUCCESS
  
  $ cd distribution
  $ mvn clean install
  …(中略)
  [INFO] BUILD SUCCESS
  ```

## ビルドしたKeycloakの動作確認

1. ビルドしたKeycloakの動作を確認します。正しく起動すると、コンソールに`Started Keycloak (http://localhost:8081/auth) in XXXX ms`のメッセージが表示されます。
   
   ```shell-session
   $ 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
   ```

2. WebブラウザのURL欄に[http://localhost:8081/auth](http://localhost:8081/auth)を入力し起動を確認します。
   ![Keycloak_top_no_select.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/73e00aeb-5ac9-bee0-b9c1-b82f57c90211.png)

# IDE環境の設定

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

1. [**Pleiades All in One Eclipse**](https://mergedoc.osdn.jp/)のダウンロードリンクより、[**Mac > Java**](https://ftp.jaist.ac.jp/pub/mergedoc/pleiades/2023/pleiades-2023-03-java-mac-jre_20230326.dmg)をクリックして、インストーラーをダウンロードします。
   ![Pleiades_All_in_One_Eclipse.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/e9944a84-7597-7973-708f-fb7f48b0b3a3.png)

2. ダウンロード後、pleiades-2023-03-java-mac-jre_20230326.dmgをダブルクリックして、

3. pleiades_2023_03アイコンを、アプリケーションにドラッグ&ドロップします。

## ワークスペースの指定

- アプリケーションフォルダより、pleiades_2023_03をダブルクリックして、Eclipseを起動します。
  [Keycloakビルド環境の構築](#Keycloakビルド環境の構築)で作成した、~/keycloak_workspaceをワークスペースに指定して、[起動]ボタンをクリックします。
  ![Eclipse_login.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/14094523-1d4e-d6ba-fab7-0f585db34952.png)

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


1. [Keycloakのクローン](#Keycloakのクローン)で生成したkeycloakプロジェクトを、`keycloak_workspace`へインポートします。パッケージエクスプローラを右クリックして、`[インポート…]`メニューを選択します。[Maven] > [既存 Maven プロジェクト]を選択し、[次へ>]ボタンをクリックします。
   ![import_maven_p_1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/42628b42-50be-597e-297c-22efdf242afc.png)

2. keycloakフォルダを選択し、[Open]ボタンをクリックします。
   ![import_maven_p_2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/e3096524-a878-b289-07a6-b0389a1ffffc.png)

3. keycloakフォルダの/pom.xmlファイルにチェックして、[完了]ボタンをクリックします。
   ![import_maven_p_3.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/78ef9f37-0db7-8c77-b065-3d9dcc9b3f21.png)

4. インポートが正常に完了すると、パッケージエクスプローラーが以下の状態となります。
   ![import_maven_p_4.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/f26a6a49-afb7-4b72-22a4-065f04a8523b.png)

## Keycloakのデバッグ起動の設定

1. Eclipse ツールバー・ボタン > [デバッグ▼]をクリックし、[デバッグの構成…]メニューを選択します。
   ![debug_icon.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/ed4d047a-8274-2d47-5903-91e1f0d3677f.png)
   デバッグ構成画面より、`Mavenビルド`を右クリックし、[新規構成]メニューを選択します。
   ![debug_setting_menu.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/a959ba54-6f0a-12a6-333a-cebce4e54347.png)

2. [メイン]タブを選択し、下記の項目を設定します。
   ![maven_setting_main.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/ea654517-37e8-f556-9458-a36f9f85a6c9.png)
   
   - 名前(任意)：
     
     ```
     KeycloakServer
     ```
   
   - 基底ディレクトリ：
     
     ```
     ${workspace_loc:/keycloak}
     ```
     
     ※直接入力するか、[ワークスペース…]ボタンをクリックしてkeycloakディレクトリを選択します。
   
   - ゴール：
     
     ```
     -f testsuite/utils/pom.xml exec:java -Pkeycloak-server
     ```

3. [JRE]タブを選択し、下記の項目を設定します。
   ![maven_setting_jre.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/4fc52fef-f024-4216-0bbe-a88e749e2853.png)
   
   - VM引数:
   
   ```
   -Dkeycloak.connectionsJpa.url=jdbc:h2:./keycloak;AUTO_SERVER=TRUE -Dmaven.surefire.debug=true`
   ```
   設定後、[適用]ボタンをクリックします。

## Keycloak起動確認

1. [デバッグ]ボタンをクリックしてKeycloakをデバッグ起動します。
   ![keycloak_execute.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/45fc4e71-e5ff-d30b-3ab3-03485f560f88.png)

2. コンソールで`Started Keycloak (http://localhost:8081/auth) in XXXXX ms`の表示を確認します。
   ![console_log.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/d271c573-620f-bd82-0ac8-b72c4df6f09c.png)

3. WebブラウザのURL欄に[http://localhost:8081/auth](http://localhost:8081/auth)を入力し起動を確認します。
   ![Keycloak_top.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/a56c64d3-4b6e-a26c-b821-7cb516b9b774.png)
   [Administration Console]のリンクをクリックしてログイン画面に遷移します。

4. Usernameにadmin、Passwordにadminを入力し、管理コンソールにログインします。
   ![keycloak_login.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/b43e569a-acd6-619b-f020-ce57147d3642.png)

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

1. ビルドしたKeycloakの動作を確認します。パッケージエクスプローラーより、`testsuite/utils/src/main/java/org/keycloak/testsuite/KeycloakServer.java`を選択し、394行目のstart()メソッドにブレークポイントを設定します。
   ![set_break_point.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/0146c226-37c9-e639-c946-55c5de21353a.png)

2. 前述の[#Keycloakのデバッグ起動の設定]で構成した、`KeycloakServer`の[ソース]タブ内の`ソース・ルックアップ・パス：`に、/keycloak/testsuite/util/srcを追加します。
   ![select_source.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/02352f15-353a-a248-c53a-23e8b1779469.png)
   
   - ソースの追加
     
     1. [追加…]ボタンをクリックします。
     2. `ワークスペース・フォルダー`を選択します。
     3. [追加…]ボタンをクリックします。
     4. `Keycloak > testsuite > src`を選択します。
     5. [OK]ボタンクリックします。

3. Eclipse  ツールバー・ボタン > [デバッグ▼]をクリックし、[KeycloakServer]メニューを選択して実行します。
   ![next_time_exec.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/f2336a28-8b03-3025-8cfd-b81e0dc74329.png)

4. Keycloakが起動され、目的のブレークポイントで停止したことを確認します。
   ![stop_at_breakpoint.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/792709/4110d11d-04b3-60c6-841c-7e78f9190a63.png)
   これで無事、IDEによる快適なデバッグ環境が構築できました。

# まとめ

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

# リンク

- [**Keycloak github リポジトリ**](https://github.com/keycloak/keycloak "Keycloak github リポジトリ")

- [**Keycloak 開発入門**](https://qiita.com/t-mogi/items/dc13c1c71030fcf84ad6 "Keycloak 開発入門")

- [**Keycloak by OpenStandia Advent Calendar 2017**](https://qiita.com/advent-calendar/2017/keycloak-by-openstandia "Keycloak by OpenStandia Advent Calendar 2017")