Keycloakインストール手順 Quarkus版

前提

環境情報

• Keycloakバージョン
  • 19.0.2 Quarkus版 (2022年10月3日執筆時点の最新版)
  • Keycloakは、バージョン17.0.0で従来のWildFly版からQuarkusに移行しました。WildFly版は非推奨となっております。
• サーバ
  • インスタンス
    • AWS EC2 t2.micro
    • ストレージ 10GiB
  • OS
    • CentOS-7.2009-20220825.1 (Marketplace)
• 公式ドキュメント
  • Quarkus版
    • https://www.keycloak.org/guides#server
    • https://www.keycloak.org/server/configuration
  • WildFly版 (非推奨・2022年10月3日時点)
    • https://www.keycloak.org/docs/19.0.2/server_installation/index.html

手順

1. KeycloakをインストールするサーバにSSH等でアクセスします。

2. Javaをインストールします。OpenJDK 11以上が必要です。

   1. インストール可能なOpenJDKを確認します。
      • sudo yum search openjdk
   2. Javaをインストールします。
      • sudo yum install java-11-openjdk-devel.x86_64
   3. Javaがインストールされたことを確認します。
      • java --version

3. Keycloak(Quarkus版)をインストールします。

   1. Keycloakをダウンロードします。
      • curl -OL https://github.com/keycloak/keycloak/releases/download/19.0.2/keycloak-19.0.2.tar.gz
   2. 解凍します。
      • tar -zxvf keycloak-19.0.2.tar.gz
   3. 任意のディレクトリに配置します。
      • sudo mv keycloak-19.0.2 /opt/
   4. 配置したディレクトリに移動します。
      • cd /opt/keycloak-19.0.2/

4. Keycloakの初期設定をします。 公式ドキュメント：サーバガイド > Keycloakの設定 Keycloakの設定は、優先度が高い順に以下の4種類(+α)があります。

   1. コマンドラインパラメータ
      • Keycloakを起動するときに設定します。
      • 例: bin/kc.sh start --db-url-host=mykeycloakdb
   2. 環境変数
      • サーバ毎に設定します。
      • 例: export KC_DB_URL_HOST=mykeycloakdb
   3. ユーザが作成した「.conf」ファイル
      • 設定ファイルに記述します。
      • 例: vi conf/keycloak.conf db-url-host=mykeycloakdb
      • 独自の環境変数を作ることもできます。
        • db-url-host=${MY_DB_HOST}
        • db-url-host=${MY_DB_HOST:mydb} ← デフォルト値付きの設定
   4. confディレクトリ内のkeycloak.confファイル
   5. Quarkusが提供するプロパティ
      • Keycloakではサポートされず非推奨です。
      • conf/quarkus.propertiesを作成して設定できます。

5. 必要最低限の設定をします。

   1. 管理者ID、パスワードを環境変数に設定します。
      • export KEYCLOAK_ADMIN=admin
      • export KEYCLOAK_ADMIN_PASSWORD=password
   2. ~~HTTPアクセス許可設定をします。~~
      • ~~export KC_HTTP_ENABLED=true~~
      • Keycloakを開発モードで起動する場合は、この設定が自動的に有効になります。
   3. 環境変数設定の確認
      • echo $KEYCLOAK_ADMIN
      • echo $KEYCLOAK_ADMIN_PASSWORD

6. Keycloakを開発モードで起動します。

   • ./bin/kc.sh start-dev
   • 開発モードと本番モードについては以下の公式ドキュメントを参照してください。
     • https://www.keycloak.org/server/configuration#_starting_keycloak
   • トラブルシューティング
     • エラー: ./bin/kc.sh: 行 100: java: コマンドが見つかりません
       • Javaがインストールされていないのが原因です。
       • 先にJavaをインストールする必要があります。
   • トラブルシューティング
     • エラー: ERROR [org.keycloak.services] (main) KC-SERVICES0010: Failed to add user 'admin' to realm 'master': user with username exists
       • 初期管理者がすでに存在し、起動時に環境変数がまだ存在することにより発生しています。
       • Keycloakは環境変数を無視して正常に起動するため、気にする必要はありません。気になる場合は環境変数を削除してください。
       • https://www.keycloak.org/server/configuration#_setup_of_the_initial_admin_user

7. ブラウザでKeycloakにアクセスします。

   • http://<KeycloakをインストールしたサーバのFQDN>:8080/
   • トラブルシューティング
     • 問題: HTTPS requiredが表示されてログイン画面が表示されない
       • レルムの設定で、HTTPSを必須とする設定になっています。
       • 初回起動時のオプションにstart-devと指定した場合はHTTPでもアクセスできるように設定されるとドキュメントに記載がありますが、これとは別に、レルム毎にHTTP接続を許可するかを設定する必要があります。
       • デフォルトでは、externalが設定されていて、localhostでない外部からのアクセスの場合はHTTPSが必要となります。
       • 以下の手順で、設定の確認・変更をする必要があります。
         1. ログインします。
            • ./bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user <Keycloak管理者ID> --password <Keycloak管理者パスワード>
         2. 設定を確認します。
            • ./bin/kcadm.sh get realms/master --fields sslRequired
            • externalの場合、外部からのアクセス(グローバルIPアドレス等)の際にはHTTPS接続が必要となっています。
         3. 設定をNONEに変更します。
            • ./bin/kcadm.sh update realms/master -s sslRequired=NONE
         4. 設定が変更されたことを確認します。
            • ./bin/kcadm.sh get realms/master --fields sslRequired

関連資料

• すべての設定項目は以下の公式ドキュメントで確認できます。
  • サーバガイド > All configuration
• KeycloakをSystemdのserviceとして実行する方法について、公式のGitHubで議論されています。
  • Write a guide about starting the server as a systemd service