LoginSignup
4
2
@Yubi-Saburo(Yubi Saburo)in日本情報システム株式会社

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

Last updated at Posted at 2023-06-16

はじめに

現在、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のインストール

  1. 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で動作検証を行いました。)

  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のバージョンを確認します。

    $ 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のインストールとバージョンの確認

    $ 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の定義を追加します。

    …(中略)
  <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の動作確認

  1. ビルドした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

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

IDE環境の設定

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

  1. Pleiades All in One Eclipseのダウンロードリンクより、Mac > Javaをクリックして、インストーラーをダウンロードします。
    Pleiades_All_in_One_Eclipse.png

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

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

ワークスペースの指定

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

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

  1. Keycloakのクローンで生成したkeycloakプロジェクトを、keycloak_workspaceへインポートします。パッケージエクスプローラを右クリックして、[インポート…]メニューを選択します。[Maven] > [既存 Maven プロジェクト]を選択し、[次へ>]ボタンをクリックします。
    import_maven_p_1.png

  2. keycloakフォルダを選択し、[Open]ボタンをクリックします。
    import_maven_p_2.png

  3. keycloakフォルダの/pom.xmlファイルにチェックして、[完了]ボタンをクリックします。
    import_maven_p_3.png

  4. インポートが正常に完了すると、パッケージエクスプローラーが以下の状態となります。
    import_maven_p_4.png

Keycloakのデバッグ起動の設定

  1. Eclipse ツールバー・ボタン > [デバッグ▼]をクリックし、[デバッグの構成…]メニューを選択します。
    debug_icon.png
    デバッグ構成画面より、Mavenビルドを右クリックし、[新規構成]メニューを選択します。
    debug_setting_menu.png

  2. [メイン]タブを選択し、下記の項目を設定します。
    maven_setting_main.png

    • 名前(任意)：

      KeycloakServer

    • 基底ディレクトリ：

      ${workspace_loc:/keycloak}

      ※直接入力するか、[ワークスペース…]ボタンをクリックしてkeycloakディレクトリを選択します。

    • ゴール：

      -f testsuite/utils/pom.xml exec:java -Pkeycloak-server

  3. [JRE]タブを選択し、下記の項目を設定します。
    maven_setting_jre.png

    • VM引数:
    -Dkeycloak.connectionsJpa.url=jdbc:h2:./keycloak;AUTO_SERVER=TRUE -Dmaven.surefire.debug=true`

    設定後、[適用]ボタンをクリックします。

Keycloak起動確認

  1. [デバッグ]ボタンをクリックしてKeycloakをデバッグ起動します。
    keycloak_execute.png

  2. コンソールでStarted Keycloak (http://localhost:8081/auth) in XXXXX msの表示を確認します。
    console_log.png

  3. WebブラウザのURL欄にhttp://localhost:8081/authを入力し起動を確認します。
    Keycloak_top.png
    [Administration Console]のリンクをクリックしてログイン画面に遷移します。

  4. Usernameにadmin、Passwordにadminを入力し、管理コンソールにログインします。
    keycloak_login.png

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

  1. ビルドしたKeycloakの動作を確認します。パッケージエクスプローラーより、testsuite/utils/src/main/java/org/keycloak/testsuite/KeycloakServer.javaを選択し、394行目のstart()メソッドにブレークポイントを設定します。
    set_break_point.png

  2. 前述の[#Keycloakのデバッグ起動の設定]で構成した、KeycloakServerの[ソース]タブ内のソース・ルックアップ・パス：に、/keycloak/testsuite/util/srcを追加します。
    select_source.png

    • ソースの追加

      1. [追加…]ボタンをクリックします。
      2. ワークスペース・フォルダーを選択します。
      3. [追加…]ボタンをクリックします。
      4. Keycloak > testsuite > srcを選択します。
      5. [OK]ボタンクリックします。

  3. Eclipse ツールバー・ボタン > [デバッグ▼]をクリックし、[KeycloakServer]メニューを選択して実行します。
    next_time_exec.png

  4. Keycloakが起動され、目的のブレークポイントで停止したことを確認します。
    stop_at_breakpoint.png
    これで無事、IDEによる快適なデバッグ環境が構築できました。

まとめ

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

リンク

4
2
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
4
2