前提
この記事は、Quarkus版を対象としています。
WildFly版のインストール手順は、以前の記事をご覧ください。
AWSにKeycloakをスタンドアロンでインストールする手順
環境情報
- 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
- Quarkus版
手順
- KeycloakをインストールするサーバにSSH等でアクセスします。
Javaをインストールします。OpenJDK 11以上が必要です。
- インストール可能なOpenJDKを確認します。
sudo yum search openjdk
- Javaをインストールします。
sudo yum install java-11-openjdk-devel.x86_64
- Javaがインストールされたことを確認します。
java --version
- インストール可能なOpenJDKを確認します。
Keycloak(Quarkus版)をインストールします。
- Keycloakをダウンロードします。
- curl -OL https://github.com/keycloak/keycloak/releases/download/19.0.2/keycloak-19.0.2.tar.gz
- 解凍します。
tar -zxvf keycloak-19.0.2.tar.gz
- 任意のディレクトリに配置します。
sudo mv keycloak-19.0.2 /opt/
- 配置したディレクトリに移動します。
cd /opt/keycloak-19.0.2/
- Keycloakをダウンロードします。
Keycloakの初期設定をします。 公式ドキュメント:サーバガイド > Keycloakの設定 Keycloakの設定は、優先度が高い順に以下の4種類(+α)があります。
- コマンドラインパラメータ
- Keycloakを起動するときに設定します。
- 例:
bin/kc.sh start --db-url-host=mykeycloakdb
- 環境変数
- サーバ毎に設定します。
- 例:
export KC_DB_URL_HOST=mykeycloakdb
- ユーザが作成した「.conf」ファイル
- 設定ファイルに記述します。
- 例:
vi conf/keycloak.conf
db-url-host=mykeycloakdb
- 独自の環境変数を作ることもできます。
db-url-host=${MY_DB_HOST}
db-url-host=${MY_DB_HOST:mydb}
← デフォルト値付きの設定
- confディレクトリ内のkeycloak.confファイル
- Quarkusが提供するプロパティ
- Keycloakではサポートされず非推奨です。
conf/quarkus.properties
を作成して設定できます。
- コマンドラインパラメータ
必要最低限の設定をします。
- 管理者ID、パスワードを環境変数に設定します。
export KEYCLOAK_ADMIN=admin
export KEYCLOAK_ADMIN_PASSWORD=password
- ~~HTTPアクセス許可設定をします。~~
- ~~
export KC_HTTP_ENABLED=true
~~ - Keycloakを開発モードで起動する場合は、この設定が自動的に有効になります。
- ~~
- 環境変数設定の確認
echo $KEYCLOAK_ADMIN
echo $KEYCLOAK_ADMIN_PASSWORD
- 管理者ID、パスワードを環境変数に設定します。
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
- エラー:
ブラウザでKeycloakにアクセスします。
- http://<KeycloakをインストールしたサーバのFQDN>:8080/
- トラブルシューティング
- 問題:
HTTPS required
が表示されてログイン画面が表示されない- レルムの設定で、HTTPSを必須とする設定になっています。
- 初回起動時のオプションに
start-dev
と指定した場合はHTTPでもアクセスできるように設定されるとドキュメントに記載がありますが、これとは別に、レルム毎にHTTP接続を許可するかを設定する必要があります。 - デフォルトでは、
external
が設定されていて、localhostでない外部からのアクセスの場合はHTTPSが必要となります。 - 以下の手順で、設定の確認・変更をする必要があります。
- ログインします。
./bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user <Keycloak管理者ID> --password <Keycloak管理者パスワード>
- 設定を確認します。
./bin/kcadm.sh get realms/master --fields sslRequired
- externalの場合、外部からのアクセス(グローバルIPアドレス等)の際にはHTTPS接続が必要となっています。
- 設定を
NONE
に変更します。./bin/kcadm.sh update realms/master -s sslRequired=NONE
- 設定が変更されたことを確認します。
./bin/kcadm.sh get realms/master --fields sslRequired
- ログインします。
- 問題:
関連資料
- すべての設定項目は以下の公式ドキュメントで確認できます。
- KeycloakをSystemdのserviceとして実行する方法について、公式のGitHubで議論されています。
- コメントを追加
- 閲覧数 4562
とても参考になりました
初めまして、会内でSSOを実施するためにKeycloak 23.0.3をDocker で立ち上げてNextcloud と連携を計画して、作業をしていますが上手くいかない状況です、単独で立ち上げた方が色々と融通がきくので、貴殿のサイトを参考に19.0.2を立ち上げました、この環境でNextcloud と連携を試していきたいと思っています
コメントを追加