サーバー設定ガイド

Red Hat build of Keycloak は、次の 4 つのソースから設定をロードします。ここでは適用順にリストされています。

オプションが複数のソースに設定されている場合、そのオプションの値はリストの最初にあるソースにより決定されます。たとえば、コマンドラインパラメーターにより設定されたオプションの値は、同じオプションの環境変数よりも優先されます。

この設定では、ソースごとに統一された 形式が使用されており、キー/値ペアの、ある設定ソースから別の設定ソースへの変換が簡素化されます。この形式は spi オプションにも適用されることに注意してください。

設定の各章の最後で、該当する設定形式を定義する 関連オプション の見出しを探してください。すべての設定オプションは、すべての設定 を参照してください。ユースケースに適用できる設定ソースと形式を選択します。

bin/kc.[sh|bat] start --db-url-host=mykeycloakdb

export KC_DB_URL_HOST=mykeycloakdb

db-url-host=mykeycloakdb

bin/kc.[sh|bat] start --help

db-url-host=${MY_DB_HOST}

db-url-host=${MY_DB_HOST:mydb}

bin/kc.[sh|bat] --config-file=/path/to/myconfig.conf start

keytool -importpass -alias kc.db-password -keystore keystore.p12 -storepass keystorepass -storetype PKCS12 -v

bin/kc.[sh|bat] start --config-keystore=/path/to/keystore.p12 --config-keystore-password=keystorepass --config-keystore-type=PKCS12

.\kc.bat start --log-level='"INFO,org.hibernate:debug"'

Red Hat build of Keycloak は、development mode または production mode で起動できます。各モードでは、対象となる環境に応じて異なるデフォルトが提供されます。

bin/kc.[sh|bat] start-dev

bin/kc.[sh|bat] start

初期管理者ユーザーは、ローカル接続 (localhost) を使用してアクセスする Web フロントエンドを使用して作成できます。代わりに、環境変数を使用してこのユーザーを作成することもできます。初期管理者ユーザー名には KC_BOOTSTRAP_ADMIN_USERNAME=<username> を設定し、初期管理者パスワードには KC_BOOTSTRAP_ADMIN_PASSWORD=<password> を設定します。

Red Hat build of Keycloak は、初回起動時にこれらの値を解析して、管理者権限を持つ最初のユーザーを作成します。管理者権限を持つ最初のユーザーが存在する場合は、管理コンソールまたはコマンドラインツール kcadm.[sh|bat] を使用して追加のユーザーを作成できます。

初期管理者がすでに存在し、起動時に環境変数がまだ存在している場合は、初期管理者の作成が失敗したことを示すエラーメッセージがログに表示されます。Red Hat build of Keycloak はこの値を無視し、正しく起動します。

Red Hat build of Keycloak を実稼働環境にデプロイする前に、Red Hat build of Keycloak を最適化して起動を高速化し、メモリー消費量を改善することが推奨されます。このセクションでは、最適なパフォーマンスと実行時の動作を実現するために、Red Hat build of Keycloak の最適化を適用する方法を説明します。

bin/kc.[sh|bat] build <build-options>

bin/kc.[sh|bat] build --help

bin/kc.[sh|bat] build --db=postgres

bin/kc.[sh|bat] start --optimized <configuration-options>

一部のレルム機能により、管理者はレルムとそのコンポーネントの設定時に、環境変数やシステムプロパティーなどのシステム変数を参照できます。

デフォルトでは、Red Hat build of Keycloak ではシステム変数の使用は許可されておらず、spi-admin-allowed-system-variables 設定オプションで明示的に指定された変数のみ使用できます。このオプションを使用すると、最終的に同じキーを持つシステム変数の値に解決されるキーのコンマ区切りリストを指定できます。

今後のリリースでは、レルム設定でのシステム変数の使用を防止するために、この機能は削除されます。

このセクションでは、Red Hat build of Keycloak が使用する基礎となる概念、特に起動の最適化にかかわる概念を説明します。

Red Hat build of Keycloak は、Quarkus フレームワークと再拡張/mutable-jar アプローチを内部で使用します。このプロセスは、build コマンドが実行されると開始されます。

以下は、build コマンドにより実行される最適化の一部です。

詳細は、該当する Quarkus ガイド を参照してください。

Red Hat build of Keycloak は、継続的に機密データを交換します。つまり、Red Hat build of Keycloak との間のすべての通信には、セキュアな通信チャネルが必要です。さまざまな攻撃ベクトルを防ぐには、そのチャネルに対して HTTP over TLS (HTTPS) を有効にします。

Red Hat build of Keycloak のためにセキュアな通信チャネルを設定するには、TLS の設定 および 送信 HTTP 要求の設定 を参照してください。

Red Hat build of Keycloak のキャッシュ通信を保護するには、分散キャッシュの設定 を参照してください。

通常、実稼働環境では、Red Hat build of Keycloak インスタンスはプライベートネットワークで実行されます。しかし、保護すべきアプリケーションと通信するために、Red Hat build of Keycloak は特定のパブリック向けエンドポイントを公開する必要があります。

エンドポイントカテゴリーの詳細と、それらのパブリックホスト名を設定する方法は、ホスト名の設定 (v2) を参照してください。

通常、ホスト名の設定 (v2) とは別に、実稼働環境にはリバースプロキシー/ロードバランサーコンポーネントが含まれています。これは、会社や組織が使用するネットワークへのアクセスの分離や統合を行います。Red Hat build of Keycloak の実稼働環境では、このコンポーネントが推奨されます。

Red Hat build of Keycloak でプロキシー通信モードを設定する方法の説明は、リバースプロキシーの設定 を参照してください。Red Hat build of Keycloak がアプリケーションを保護するために、パブリックアクセスから隠すべきパスと、公開すべきパスに関する推奨も記載されています。

実稼働環境では、過負荷状態から保護して、可能な限り多くの有効な要求に応答し、状況が正常に戻ったときに通常の操作を継続できるようにする必要があります。これを実現する 1 つの方法は、特定のしきい値に達したときに追加の要求を拒否することです。

負荷制限は、環境内のロードバランサーを含むすべてのレベルで実装する必要があります。さらに、Red Hat build of Keycloak には、すぐに処理できないためキューに入れる必要がある要求の数を制限する機能があります。デフォルトでは制限は設定されていません。オプション http-max-queued-requests を設定すると、キューに入れる要求の数を、環境に合わせて特定のしきい値に制限できます。この制限を超える要求には、即時に 503 Server not Available 応答が返されます。

Red Hat build of Keycloak で使用されるデータベースは、Red Hat build of Keycloak の全体的なパフォーマンス、可用性、信頼性、整合性において非常に重要です。サポート対象データベースの設定方法の説明は、データベースの設定 を参照してください。

Red Hat build of Keycloak インスタンスがダウンした場合もユーザーのログインを継続するために、一般的な実稼働環境には Red Hat build of Keycloak インスタンスが 2 つ以上含まれています。

Red Hat build of Keycloak は、JGroups および Infinispan 上で実行されます。これらは、クラスター化されている場合に高い信頼性と可用性を提供します。デフォルトのセットアップでは、ノード間の通信は TLS を使用して暗号化されます。

複数のノード、さまざまなキャッシュ、環境に適したスタックを使用する場合の詳細は、分散キャッシュの設定 を参照してください。

システムプロパティーである java.net.preferIPv4Stack と java.net.preferIPv6Addresses を使用して、IPv4 または IPv6 アドレスを使用するように JVM を設定できます。

デフォルトでは、Red Hat build of Keycloak は、同時に IPv4 アドレスと IPv6 アドレスを介してアクセスできます。IPv4 アドレスのみで実行する場合は、プロパティー java.net.preferIPv4Stack=true を指定する必要があります。そうすることで、ホスト名から IP アドレスへの変換では必ず IPv4 アドレスのバリアントが返されるようになります。

これらのシステムプロパティーは、JAVA_OPTS_APPEND 環境変数を使用して容易に設定できます。たとえば、IP スタック設定を IPv4 に変更するには、次のように環境変数を設定します。

export JAVA_OPTS_APPEND="-Djava.net.preferIPv4Stack=true"

IPv6 専用サーバーを設定するには、分散キャッシュがクラスターを形成するように環境変数を次のように設定します。

export JAVA_OPTS_APPEND="-Djava.net.preferIPv4Stack=false -Djava.net.preferIPv6Addresses=true"

詳細は、分散キャッシュの設定 を参照してください。

以下に説明するいずれかの方法を使用して作成されたユーザーまたはサービス管理者アカウントは 一時的 なものです。つまり、アカウントは、永続的でよりセキュアな管理者アクセスを取得するために必要な操作を実行するために必要な期間のみ存在する必要があります。その後、アカウントを手動で削除する必要があります。管理コンソールの警告バナー、ラベル、ログメッセージなどのさまざまな UI/UX 要素によって、アカウントが一時的であることが Red Hat build of Keycloak 管理者に通知されます。

Red Hat build of Keycloak の start および start-dev コマンドは、一時的な管理者ユーザーと管理サービスアカウントの両方をブートストラップするためのオプションをサポートします。これらのオプションは標準の設定オプションであるため、環境変数や CLI パラメーターなどの任意の 設定ソース で指定できます。たとえば、次の例は、CLI パラメーターを指定した start コマンドと start-dev コマンドを使用して、それぞれ一時的な管理者ユーザーと管理者サービスアカウントをブートストラップする方法を示しています。

bin/kc.[sh|bat] start --bootstrap-admin-username tmpadm --bootstrap-admin-password pass

bin/kc.[sh|bat] start-dev --bootstrap-admin-client-id tmpadm --bootstrap-admin-client-secret secret

ユーザー名またはクライアント ID の値は省略できます。詳細は、以下の 「デフォルト値」 セクションを参照してください。

これらのオプションの目的は、一時的な管理者アカウントをブートストラップすることだけです。これらのアカウントは、マスターレルムがまだ存在しないときに、Red Hat build of Keycloak サーバーの初期起動時にのみ作成されます。アカウントは常にマスターレルムに作成されます。失われた管理者アクセスを回復するには、以下のセクションで説明する専用コマンドを使用します。

bootstrap-admin コマンドは、Red Hat build of Keycloak を初めて起動する前でも実行できます。このコマンドを使用する前に、すべての Red Hat build of Keycloak ノードを停止する必要があることに注意してください。これを実行すると、初期マスターレルムの作成がトリガーされ、その結果、後でサーバーが初めて起動されるときに、管理者ユーザーとサービスアカウントをブートストラップするための起動オプションは無視されます。

さらに、Red Hat build of Keycloak サーバーの起動時と同じオプション (例: db オプション) を指定して専用コマンドを使用することを強く推奨します。

Red Hat build of Keycloak の設定 で説明されているように、build コマンドを使用して Red Hat build of Keycloak の最適化バージョンをビルドした場合は、コマンドラインオプション --optimized を使用して、起動時間を短縮するために Red Hat build of Keycloak がビルドチェックをスキップするようにします。その際には、コマンドラインからビルド時オプションを削除し、実行時オプションのみを保持します。

bin/kc.[sh|bat] bootstrap-admin user

bin/kc.[sh|bat] bootstrap-admin user --username tmpadm --password:env PASS_VAR

bin/kc.[sh|bat] bootstrap-admin service

bin/kc.[sh|bat] bootstrap-admin service --client-id tmpclient --client-secret:env=SECRET_VAR

管理者アクセスが失われたレルムに対して、パスワードレス、OTP、またはその他の高度な認証方法を適用できます。このような場合、レルムへの失われた管理者アクセスを回復するには、管理者サービスアカウントを作成する必要があります。サービスアカウントが作成された後、必要なすべての操作を実行するには、Red Hat build of Keycloak インスタンスに対する認証が必要です。

bin/kcadm.[sh|bat] config credentials --server http://localhost:8080 --realm master --client <service_account_client_name> --secret <service_account_secret>

次に、credentialId を取得します。この例では、OTP 認証情報が関連する認証情報です。次のコマンドを使用して、CredentialRepresentation オブジェクトの配列を取得し、type が otp に設定されているオブジェクトを見つけます。

bin/kcadm.[sh|bat] get users/{userId}/credentials -r {realm-name}

最後に、取得した ID を使用して、高度な認証方法 (この場合は OTP) を削除できます。

bin/kcadm.[sh|bat] delete users/{userId}/credentials/{credentialId} -r {realm-name}

起動および専用コマンドの両方のシナリオでは、ユーザー名とクライアント ID はオプションであり、ユーザーアカウントとサービスアカウントの両方でそれぞれ temp-admin がデフォルトになります。

--no-prompt パラメーターを使用して、パラメーターのプロンプトを無効化できます。以下に例を示します。

bin/kc.[sh|bat] bootstrap-admin user --username tmpadm --no-prompt

対応する環境変数が設定されていない場合、コマンドは失敗し、必要なパスワードパラメーターがないことを示すエラーメッセージが表示されます。

--no-prompt パラメーターは、ユーザー名またはクライアント ID を省略する必要がある場合に役立ちます。以下に例を示します。

bin/kc.[sh|bat] bootstrap-admin user --password:env PASS_VAR --no-prompt

これにより、確認を求めることなく、デフォルトのユーザー名を持つ一時的な管理者ユーザーが作成されます。詳細は、上記の 「デフォルト値」 セクションを参照してください。

bootstrap-admin user コマンドでは、ユーザー名とパスワードの両方をオプションで環境変数として設定できます。

bin/kc.[sh|bat] bootstrap-admin user --username:env <YourUsernameEnv> --password:env <YourPassEnv>

bootstrap-admin service コマンドの場合、クライアント ID はオプションで、デフォルトは temp-admin ですが、クライアントシークレットは環境変数として設定する必要があります。

bin/kc.[sh|bat] bootstrap-admin service --client-id:env <YourClientIdEnv> --client-secret:env <YourSecretEnv>

zip ファイルからインストールする場合、デフォルトで rhbk-26.2.12 のインストール root ディレクトリーがあります。 このディレクトリーは、ファイルシステム上で選択した場所に作成できます。

/opt/keycloak は、Red Hat build of Keycloak で示されるすべてのコンテナー化された使用法におけるサーバーのルートインストールロケーションです。

Red Hat build of Keycloak のインストールルートの下には、いくつかのフォルダーが存在します。

デフォルトの Red Hat build of Keycloak コンテナーイメージは、すぐに設定および最適化できる状態で出荷されます。

Red Hat build of Keycloak コンテナーを最適に起動するには、コンテナーのビルド中に build ステップを実行してイメージをビルドします。この手順を実行することで、後に続くコンテナーイメージの各起動フェーズで時間を節約できます。

FROM registry.redhat.io/rhbk/keycloak-rhel9:26.2 AS builder

# Enable health and metrics support
ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true

# Configure a database vendor
ENV KC_DB=postgres

WORKDIR /opt/keycloak
# for demonstration purposes only, please make sure to use proper certificates in production instead
RUN keytool -genkeypair -storepass password -storetype PKCS12 -keyalg RSA -keysize 2048 -dname "CN=server" -alias server -ext "SAN:c=DNS:localhost,IP:127.0.0.1" -keystore conf/server.keystore
RUN /opt/keycloak/bin/kc.sh build

FROM registry.redhat.io/rhbk/keycloak-rhel9:26.2
COPY --from=builder /opt/keycloak/ /opt/keycloak/

# change these values to point to a running postgres instance
ENV KC_DB=postgres
ENV KC_DB_URL=<DBURL>
ENV KC_DB_USERNAME=<DBUSERNAME>
ENV KC_DB_PASSWORD=<DBPASSWORD>
ENV KC_HOSTNAME=localhost
ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

# A example build step that downloads a JAR file from a URL and adds it to the providers directory
FROM registry.redhat.io/rhbk/keycloak-rhel9:26.2 as builder

...

# Add the provider JAR file to the providers directory
ADD --chown=keycloak:keycloak --chmod=644 <MY_PROVIDER_JAR_URL> /opt/keycloak/providers/myprovider.jar

...

# Context: RUN the build command
RUN /opt/keycloak/bin/kc.sh build

FROM registry.access.redhat.com/ubi9 AS ubi-micro-build
COPY mycertificate.crt /etc/pki/ca-trust/source/anchors/mycertificate.crt
RUN update-ca-trust

FROM registry.redhat.io/rhbk/keycloak-rhel9
COPY --from=ubi-micro-build /etc/pki /etc/pki

FROM registry.access.redhat.com/ubi9 AS ubi-micro-build
RUN mkdir -p /mnt/rootfs
RUN dnf install --installroot /mnt/rootfs <package names go here> --releasever 9 --setopt install_weak_deps=false --nodocs -y && \
    dnf --installroot /mnt/rootfs clean all && \
    rpm --root /mnt/rootfs -e --nodeps setup

FROM registry.redhat.io/rhbk/keycloak-rhel9
COPY --from=ubi-micro-build /mnt/rootfs /

#!/bin/bash

# (add your custom logic here)

# Run the 'exec' command as the last step of the script.
# As it replaces the current shell process, no additional shell commands will run after the 'exec' command.
exec /opt/keycloak/bin/kc.sh start "$@"

podman build . -t mykeycloak

podman run --name mykeycloak -p 8443:8443 -p 9000:9000 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        mykeycloak \
        start --optimized --hostname=localhost

...
RUN ulimit -n 1024000 && dnf install --installroot ...
...

...
# ADD or copy one or more provider jars
ADD --chown=keycloak:keycloak --chmod=644 some-jar.jar /opt/keycloak/providers/
...
RUN touch -m --date=@1743465600 /opt/keycloak/providers/*
RUN /opt/keycloak/bin/kc.sh build
...

デフォルトで、サーバーはポート 8080 と 8443 を使用して、それぞれ http 要求と https 要求をリッスンします。

別のポートを使用してコンテナーを公開する場合は、それに応じて hostname を設定する必要があります。

podman run --name mykeycloak -p 3000:8443 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        mykeycloak \
        start --optimized --hostname=https://localhost:3000

hostname オプションを完全な URL に設定すると、https://localhost:3000 でサーバーにアクセスできるようになります。

開発またはテスト目的でコンテナーから Red Hat build of Keycloak を試用する場合、開発モードが最適です。start-dev コマンドを使用します。

podman run --name mykeycloak -p 8080:8080 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        registry.redhat.io/rhbk/keycloak-rhel9:26.2 \
        start-dev

このコマンドを呼び出すと、Red Hat build of Keycloak サーバーが開発モードで起動します。

このモードはデフォルトがセキュアではないため、実稼働環境では絶対に使用しないでください。Red Hat build of Keycloak を実稼働環境で実行する方法の詳細は、Red Hat build of Keycloak を実稼働用に設定する を参照してください。

イミュータブルインフラストラクチャーなどの概念に従い、コンテナーは定期的に再プロビジョニングする必要があります。これらの環境では、素早く起動するコンテナーが必要なため、前のセクションで説明したように、最適化されたイメージを作成する必要があります。ただし、環境に異なる要件がある場合は、start コマンドを実行するだけで標準の Red Hat build of Keycloak イメージを実行できます。以下に例を示します。

podman run --name mykeycloak -p 8080:8080 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        registry.redhat.io/rhbk/keycloak-rhel9:26.2 \
        start \
        --db=postgres --features=token-exchange \
        --db-url=<JDBC-URL> --db-username=<DB-USER> --db-password=<DB-PASSWORD> \
        --https-key-store-file=<file> --https-key-store-password=<password>

このコマンドを実行すると、最初にビルドオプションを検出して適用する Red Hat build of Keycloak サーバーが起動します。この例では、--db=postgres --features=token-exchange の行でデータベースベンダーが PostgreSQL に設定され、トークン交換機能が有効になります。

その後、Red Hat build of Keycloak が起動し、設定が環境に適用されます。このアプローチでは起動時間が大幅に増加し、ミュータブルなイメージが作成されますが、これはベストプラクティスではありません。

Red Hat build of Keycloak では、ローカルネットワーク接続からのみ初期管理者ユーザーを作成できます。コンテナー内で実行する場合、これは当てはまりません。そのため、イメージ実行時に次の環境変数を指定する必要があります。

# setting the admin username
-e KC_BOOTSTRAP_ADMIN_USERNAME=<admin-user-name>

# setting the initial password
-e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me

Red Hat build of Keycloak コンテナーには、ディレクトリー /opt/keycloak/data/import があります。ボリュームマウントまたはその他の手段でこのディレクトリーに 1 つ以上のインポートファイルを配置し、起動引数 --import-realm を追加すると、Red Hat build of Keycloak コンテナーが起動時にそのデータをインポートします。これは、開発モードでのみの使用が合理的です。

podman run --name keycloak_unoptimized -p 8080:8080 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        -v /path/to/realm/data:/opt/keycloak/data/import \
        registry.redhat.io/rhbk/keycloak-rhel9:26.2 \
        start-dev --import-realm

管理者ブートストラッププロセスの機能強化は、誰でも参加できる GitHub ディスカッション があります。お気軽にご参加ください。

Red Hat build of Keycloak コンテナーでは、初期ヒープサイズと最大ヒープサイズにハードコード値を指定せずに、コンテナーの合計メモリーに対する相対値を使用します。この動作は、JVM オプション -XX:MaxRAMPercentage=70 および -XX:InitialRAMPercentage=50 によって実現されます。

-XX:MaxRAMPercentage オプションは、最大ヒープサイズをコンテナーメモリーの合計の 70% として表します。-XX:InitialRAMPercentage オプションは、初期ヒープサイズをコンテナーメモリー全体の 50% として表します。これらの値は、Red Hat build of Keycloak メモリー管理の詳細な分析に基づいて選択されています。

ヒープサイズはコンテナーの合計メモリーに基づいて動的に計算されるため、コンテナーの メモリー制限を必ず設定 してください。以前は、最大ヒープサイズは 512 MB に設定されていましたが、同じ値に近づけるには、メモリー制限を少なくとも 750 MB に設定する必要があります。小規模な実稼働環境対応のデプロイメントの場合、推奨されるメモリー制限は 2 GB です。

ヒープに関連する JVM オプションは、環境変数 JAVA_OPTS_KC_HEAP を設定することによってオーバーライドされる可能性があります。JAVA_OPTS_KC_HEAP のデフォルト値は、kc.sh または kc.bat スクリプトのソースコードにあります。

たとえば、環境変数とメモリー制限を次のように指定できます。

podman run --name mykeycloak -p 8080:8080 -m 1g \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        -e JAVA_OPTS_KC_HEAP="-XX:MaxHeapFreeRatio=30 -XX:MaxRAMPercentage=65" \
        registry.redhat.io/rhbk/keycloak-rhel9:26.2 \
        start-dev

PEM 形式の証明書ファイルと秘密鍵ファイルのペアを使用する場合は、次のコマンドを実行して、それらを使用するように Red Hat build of Keycloak を設定します。

bin/kc.[sh|bat] start --https-certificate-file=/path/to/certfile.pem --https-certificate-key-file=/path/to/keyfile.pem

Red Hat build of Keycloak は、メモリー内のこれらのファイルからキーストアを作成し、以降はこのキーストアを使用します。

キーストアファイルが明示的に設定されておらず、http-enabled が false に設定されている場合、Red Hat build of Keycloak は conf/server.keystore ファイルを探します。

代わりに、次のコマンドを実行して既存のキーストアを使用することもできます。

bin/kc.[sh|bat] start --https-key-store-file=/path/to/existing-keystore-file

キーストアで認識されるファイル拡張子:

ファイルタイプに一致する拡張子がキーストアにない場合は、https-key-store-type オプションも設定する必要があります。

bin/kc.[sh|bat] start --https-key-store-password=<value>

デフォルトでは、Red Hat build of Keycloak は非推奨の TLS プロトコルを有効にしません。クライアントが非推奨のプロトコルのみをサポートしている場合は、クライアントのアップグレードを検討してください。一時的な回避策として、次のコマンドを実行し、非推奨のプロトコルを有効にできます。

bin/kc.[sh|bat] start --https-protocols=<protocol>[,<protocol>]

たとえば、TLSv1.3 のみを有効にするには、kc.sh start --https-protocols=TLSv1.3 のコマンドを使用します。

Red Hat build of Keycloak は、ポート 8443 で HTTPS トラフィックをリッスンします。このポートを変更するには、次のコマンドを使用します。

bin/kc.[sh|bat] start --https-port=<port>

デフォルトでは、Red Hat build of Keycloak は、https-* オプションで指定された証明書、キー、およびキーストアを 1 時間ごとに再ロードします。サーバーキーを頻繁にローテーションする必要がある環境では、サーバーを再起動せずにローテーションを実行できます。https-certificates-reload-period オプションを使用してデフォルトをオーバーライドできます。https-* オプションによって参照されるキーストア、トラストストア、および証明書ファイルを再ロードする間隔。値は、java.time.Duration 値、秒数を表す整数、または整数の後に時間単位 [ms、h、m、s、d] のいずれかが続く値になります。30 秒より長くする必要があります。無効にするには -1 を使用します。

デフォルトでは、Red Hat build of Keycloak では hostname オプションの設定が必須であり、URL は動的に解決されません。これはセキュリティー対策です。

Red Hat build of Keycloak は、OIDC Discovery エンドポイントを通じて、またはメール内のパスワードリセットリンクの一部として、独自の URL を自由に公開します。ホスト名がホスト名ヘッダーから動的に解釈されると、潜在的な攻撃者にメール内の URL を操作し、ユーザーを攻撃者の偽のドメインにリダイレクトし、アクショントークンやパスワードなどの機密データを盗む機会を与える可能性があります。

hostname オプションを明示的に設定することで、不正な発行者によってトークンが発行される状況を回避します。次のコマンドを使用して、明示的なホスト名でサーバーを起動できます。

bin/kc.[sh|bat] start --hostname my.keycloak.org

前の例で示したように、スキームとポートは明示的には必要ありません。このような場合、Red Hat build of Keycloak はこれらの側面を自動的に処理します。たとえば、上記の例では、サーバーは https://my.keycloak.org:8443 でアクセスできます。ただし、リバースプロキシーは通常、デフォルトのポート (例: 443) で Red Hat build of Keycloak を公開します。その場合、URL の一部を動的に保つのではなく、hostname オプションで完全な URL を指定することが望ましいです。その後、次のコマンドでサーバーを起動できます。

bin/kc.[sh|bat] start --hostname https://my.keycloak.org

同様に、リバースプロキシーは、異なるコンテキストパスで Red Hat build of Keycloak を公開する場合があります。hostname および hostname-admin オプションを使用して、それを反映するように Red Hat build of Keycloak を設定できます。以下の例を参照してください。

bin/kc.[sh|bat] start --hostname https://my.keycloak.org:123/auth

Red Hat build of Keycloak には、バックチャネルリクエスト用に別の URL を提供できる機能があり、フロントチャネルリクエスト用のパブリック URL の使用を維持しながら内部通信を可能にします。さらに、バックチャネルは受信ヘッダーに基づいて動的に解決されます。以下の例を考慮してください。

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-backchannel-dynamic true

この方法では、クライアントと呼ばれるアプリケーションは、ローカルネットワークを介して Red Hat build of Keycloak に接続できますが、サーバーは https://my.keycloak.org でパブリックにアクセス可能なままになります。

ご覧のとおり、HTTPS プロトコルは、Red Hat build of Keycloak のセキュリティーのベストプラクティスへの取り組みに準拠したデフォルトの選択です。ただし、Red Hat build of Keycloak では、必要に応じてユーザーが HTTP を選択できる柔軟性も提供されます。これは、HTTP リスナーを指定するだけで実現できます。詳細は、TLS の設定 を参照してください。エッジ TLS-termination プロキシーを使用すると、次のようにサーバーを起動できます。

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --http-enabled true

この設定の結果、プロキシーが HTTP とポート 8080 を使用してインスタンスと対話する一方で、HTTPS 経由で https://my.keycloak.org にある Red Hat build of Keycloak に引き続きアクセスできます。

プロキシーが http または再暗号化された TLS 要求を転送する場合は、proxy-headers オプションを設定する必要があります。ホスト名の設定に応じて、URL の一部またはすべてが動的に決定される場合があります。

bin/kc.[sh|bat] start --hostname-strict false --proxy-headers forwarded

bin/kc.[sh|bat] start --hostname my.keycloak.org --proxy-headers xforwarded

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --proxy-headers xforwarded

別のホストで管理コンソールを公開する場合は、次のコマンドを使用します。

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-admin https://admin.my.keycloak.org:8443

これにより、バックエンドは引き続き https://my.keycloak.org を使用しながら、https://my.keycloak.org にある Red Hat build of Keycloak と https://admin.my.keycloak.org:8443 にある管理コンソールにアクセスできるようになります。

Red Hat build of Keycloak は、それぞれ目的が異なる複数のエンドポイントを公開します。これらは通常、アプリケーション間の通信やサーバーの管理に使用されます。3 つの主要なエンドポイントグループを認識しています。

これらのエンドポイントのいずれかを使用する場合は、ベース URL を設定する必要があります。ベース URL は複数の部分で構成されます。

各グループのベース URL は、トークンの発行方法と検証方法、ユーザーを Red Hat build of Keycloak にリダイレクトする必要があるアクション (メールリンクを通じてパスワードをリセットする場合など) のリンクの作成方法、さらにはアプリケーションが realms/{realm-name}/.well-known/openid-configuration から OpenID Connect Discovery Document を取得する際にこれらのエンドポイントを検出する方法に重要な影響を与えます。

bin/kc.[sh|bat] start --hostname my.keycloak.org

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-backchannel-dynamic true

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-admin https://admin.my.keycloak.org:8443

前のセクションで示したように、URL はいくつかの方法で解決できます。動的に生成することも、ハードコードすることも、あるいはその両方の組み合わせで解決することもできます。

さらに、ホスト名が設定されている場合、hostname-strict は無視されます。

ホスト名の設定に対してトラブルシューティングを行うには、次のように有効にできる専用のデバッグツールを使用します。

bin/kc.[sh|bat] start --hostname=mykeycloak --hostname-debug=true

Red Hat build of Keycloak が正常に起動したら、ブラウザーを開いて http://mykeycloak:8080/realms/<your-realm>/hostname-debug にアクセスします。

Red Hat build of Keycloak はデフォルトで次のポートで実行されます。

ポート 8443 (HTTP が有効な場合は 8080) は、ホスト名の設定 (v2) の章で説明されているように、管理 UI、アカウントコンソール、SAML および OIDC エンドポイント、および管理 REST API に使用されます。

ポート 9000 は管理に使用され、管理インターフェイスの設定 の章で説明されているように、ヘルスチェックとメトリクスのエンドポイントが含まれます。

実稼働環境用の Red Hat build of Keycloak の設定 で説明されているように、フロントエンド/バックエンドと管理に異なるホスト名を使用する場合でも、ポート 8443 (または 8080) のみをプロキシーする必要があります。ヘルスチェックとメトリクスはポート 9000 を直接使用するため、ポート 9000 をプロキシーしないでください。また、この情報を外部の呼び出し元に公開しないでください。

Red Hat build of Keycloak は、proxy-headers オプションに基づいてリバースプロキシーヘッダーを解析します。このオプションは、次のいくつかの値を受け入れます。

以下に例を示します。

bin/kc.[sh|bat] start --proxy-headers forwarded

クライアントアドレスが、リバースプロキシーにより Forwarded ヘッダーまたは X-Forwarded-For ヘッダーを介して適切に設定されていることを、特に注意して確認してください。このヘッダーが正しく設定されていない場合、不正なクライアントがこのヘッダーを設定し、クライアントが実際のアドレスとは異なる IP アドレスから接続しているという誤った認識を Red Hat build of Keycloak が持つ可能性があります。IP アドレスの拒否リストまたは許可リストを作成する場合、このような注意はさらに重要です。

Red Hat build of Keycloak では、Red Hat build of Keycloak が設定されているのと同じコンテキストパスで、リバースプロキシーを通じて公開されることが想定されています。デフォルトでは、Red Hat build of Keycloak はルート (/) を通じて公開されます。これは、/ 上のリバースプロキシーを通じての公開が想定されていることを意味します。このような場合には、hostname オプションに完全な URL を使用できます。たとえば、Red Hat build of Keycloak が /auth のリバースプロキシーを通じて公開されている場合は、--hostname=https://my.keycloak.org/auth を使用します。

管理 REST API およびコンソールを含む異なるホスト名またはコンテキストパスで Red Hat build of Keycloak を公開する方法の詳細は、ホスト名の設定 (v2) を参照してください。

あるいは、http-relative-path オプションを使用して、Red Hat build of Keycloak 自体のコンテキストパスをリバースプロキシーのコンテキストパスに一致するように変更することもできます。これにより、リバースプロキシーが使用するコンテキストパスと一致するように、Red Hat build of Keycloak 自体のコンテキストパスが変更されます。

通常のクラスターデプロイメントは、プライベートネットワークにあるロードバランサー (リバースプロキシー) および 2 つ以上の Red Hat build of Keycloak サーバーで構成されます。パフォーマンスの観点からは、ロードバランサーが特定のブラウザーセッションに関連するすべての要求を同じ Red Hat build of Keycloak バックエンドノードに転送すると便利です。

なぜなら、Red Hat build of Keycloak は、現在の認証セッションとユーザーセッションに関連するデータを保存する裏で、Infinispan の分散キャッシュを使用しているためです。Infinispan 分散キャッシュは、所有者の数が制限されて設定されています。つまり、セッション関連のデータは一部のクラスターノードにのみ保存され、他のノードがそのデータにアクセスするにはリモートでデータを検索する必要があります。

たとえば、ID 123 の認証セッションが node1 の Infinispan キャッシュに保存され、node2 がこのセッションを検索する必要がある場合は、特定のセッションエンティティーを返すために、ネットワーク経由で要求を node1 に送信する必要があります。

特定のセッションエンティティーが常にローカルで利用可能な場合に利点があります。これは、スティッキーセッションを使用して実行できます。パブリックフロントエンドロードバランサーと 2 つのバックエンド Red Hat build of Keycloak ノードを持つクラスター環境のワークフローは次のようになります。

この観点から、ロードバランサーが次の要求をすべて node2 に転送することは有用です。なぜなら、これは ID 123 の認証セッションの所有者であるノードであり、Infinispan がこのセッションをローカルで検索できるからです。認証が終了すると、認証セッションはユーザーセッションに変換されます。その場合も ID 123 と同じになるため、node2 に保存されます。

クラスターの設定にスティッキーセッションは必須ではありませんが、上記の理由でパフォーマンスの観点から推奨されます。ロードバランサーを設定して、AUTH_SESSION_ID cookie でスティッキーセッションを有効にする必要があります。この変更を行うための適切な手順は、ロードバランサーによって異なります。

プロキシーがバックエンドノードからの cookie を処理せずにセッションアフィニティーをサポートする場合は、ノードを cookie にアタッチせず、リバースプロキシー機能に依存するのみにするために、spi-sticky-session-encoder-infinispan-should-attach-route オプションを false に設定する必要があります。

bin/kc.[sh|bat] start --spi-sticky-session-encoder-infinispan-should-attach-route=false

デフォルトでは、spi-sticky-session-encoder-infinispan-should-attach-route オプションの値は true であるため、ノード名は cookie にアタッチされ、リバースプロキシーには後続の要求の送信先であるノードが示されます。

リバースプロキシーを使用する場合、Red Hat build of Keycloak では特定のパスのみを公開する必要があります。次の表は、公開が推奨されるパスを示しています。

Red Hat build of Keycloak をリバースプロキシー/ゲートウェイのパブリック API のルートパス / で実行していることを前提としています。そうでない場合は、パスの前に任意の接頭辞を追加します。

プロキシーヘッダーが信頼できるプロキシーからのみ使用されるようにするには、proxy-trusted-addresses オプションを、IP アドレス (IPv4 または IPv6) または Classless Inter-Domain Routing (CIDR) 表記のコンマ区切りリストに設定します。

以下に例を示します。

bin/kc.[sh|bat] start --proxy-headers forwarded --proxy-trusted-addresses=192.168.0.32,127.0.0.0/8

proxy-protocol-enabled オプションは、プロキシーの背後からの要求を処理するときにサーバーが HA PROXY プロトコルを使用するかどうかを制御します。true に設定すると、返されるリモートアドレスは実際の接続クライアントからのアドレスになります。proxy-headers オプションを使用する場合、値を true にすることはできません。

これは、リクエストヘッダーを操作できないため、互換性のある https パススループロキシーの背後で実行する場合に役立ちます。

以下に例を示します。

bin/kc.[sh|bat] start --proxy-protocol-enabled true

プロキシーが TLS Termination プロキシーとして設定されている場合、クライアント証明書情報は特定の HTTP 要求ヘッダーを通じてサーバーに転送され、クライアントの認証に使用されます。使用しているプロキシーに応じて、サーバーがクライアント証明書情報を取得する方法を設定できます。

サーバーは、次のような最も一般的な TLS Termination プロキシーのいくつかをサポートしています。

要求からクライアント証明書を取得する方法を設定するには、以下を実行する必要があります。

bin/kc.[sh|bat] build --spi-x509cert-lookup-provider=<provider>

bin/kc.[sh|bat] start --spi-x509cert-lookup-<provider>-ssl-client-cert=SSL_CLIENT_CERT --spi-x509cert-lookup-<provider>-ssl-cert-chain-prefix=CERT_CHAIN --spi-x509cert-lookup-<provider>-certificate-chain-length=10

HTTP ヘッダーを設定する際には、使用している値が、プロキシーによってクライアント証明書情報とともに転送されるヘッダーの名前に対応していることを確認する必要があります。

プロバイダーの設定に使用できるオプションは次のとおりです。

サーバーには、各種データベースのサポートが組み込まれています。db 設定オプションの期待値を表示することで、使用可能なデータベースをクエリーできます。次の表は、サポート対象のデータベースとそのテスト済みバージョンを示しています。

デフォルトでは、サーバーは dev-file データベースを使用します。これはサーバーがデータを保持するために使用するデフォルトのデータベースであり、開発ユースケースに限定されています。dev-file データベースは実稼働環境のユースケースには適していないため、実稼働環境にデプロイする前に置き換える必要があります。

データベースドライバーは、Oracle Database および Microsoft SQL Server ドライバーを除き、Red Hat build of Keycloak の一部として出荷されます。

これらのデータベースのいずれかに接続する場合は、不足している必要なドライバーを手動でインストールしてください。データベースドライバーがすでに含まれている別のデータベースに接続する場合は、このセクションをスキップしてください。

サーバーでは、各サポート対象データベース用に、データベース設定を簡略化するための独自のデフォルトがいくつか提供されています。データベースホストや認証情報などの重要な設定を指定すると、設定が完了します。

設定は、build コマンドまたは start コマンドの実行中に設定できます。

デフォルトのスキーマは keycloak ですが、db-schema 設定オプションを使用して変更できます。

レルムのインポートとエクスポート、または 管理者アカウントのブートストラップと回復 を実行する際にデータベースを設定することもできます。

bin/kc.[sh|bat] import --help
bin/kc.[sh|bat] export --help
bin/kc.[sh|bat] bootstrap-admin --help

詳細は、Red Hat build of Keycloak の設定 を参照してください。

サーバーは、データベースとの通信の基盤となるテクノロジーとして JDBC を使用します。デフォルトの接続設定が不十分な場合は、db-url 設定オプションを使用して JDBC URL を指定できます。

以下は、PostgreSQL データベースのサンプルコマンドです。

bin/kc.[sh|bat] start --db postgres --db-url jdbc:postgresql://mypostgres/mydatabase

; などの特殊なシェル文字を含むコマンドを呼び出す場合は、CLI を使用して文字をエスケープする必要があることに注意してください。代わりに設定ファイルにそれを設定することが推奨されます。

サーバーは、選択したデータベースに応じてデフォルトの JDBC ドライバーを使用します。

別のドライバーを設定する場合は、JDBC ドライバーの完全修飾クラス名を使用して db-driver を設定できます。

bin/kc.[sh|bat] start --db postgres --db-driver=my.Driver

設定したドライバーにかかわらず、デフォルトのドライバーは実行時に常に使用できます。

本当に必要な場合にのみ、このプロパティーを設定してください。たとえば、特定のクラウドデータベースサービス用に JDBC Driver Wrapper の機能を利用する場合などです。

すべてのフィールドの Unicode サポートは、データベースが VARCHAR および CHAR フィールドで Unicode 文字セットの使用を許可するかどうかによって異なります。

データベーススキーマは、次の特殊フィールドでのみ Unicode 文字列のサポートを提供します。

それ以外の場合、データベースエンコーディングに含まれる文字に制限され、多くの場合それは 8 ビットです。ただし、データベースシステムによっては、Unicode 文字の UTF-8 エンコーディングを有効にし、すべてのテキストフィールドで完全な Unicode 文字セットを使用できます。特定のデータベースでは、この選択により、最大文字列長が 8 ビットエンコーディングでサポートされる最大文字列長よりも短くなる可能性があります。

Amazon Aurora PostgreSQL を使用する場合は、Amazon Web Services JDBC ドライバー で、マルチ AZ セットアップでライターインスタンスが変更されたときのデータベース接続の転送など、追加機能を利用できます。このドライバーはディストリビューションの一部ではないため、使用する前にインストールする必要があります。

このドライバーをインストールするには、次の手順に従います。

MySQL 8.0.30 以降、MySQL は、明示的なプライマリーキーなしで作成されたすべての InnoDB テーブルに対して生成された非表示のプライマリーキーをサポートしています (詳細は、こちら を参照してください)。この機能を有効にすると、データベーススキーマの初期化と移行が失敗し、エラーメッセージ Multiple primary key defined (1068) が表示されます。その場合、Red Hat build of Keycloak をインストールまたはアップグレードする前に、MySQL サーバー設定でパラメーター sql_generate_invisible_primary_key を OFF に設定して無効にする必要があります。

クラスターノードは同時に起動できるため、データベースのアクションに余分な時間がかかります。たとえば、起動中のサーバーインスタンスは、データベースの移行、インポート、または初回の初期化を実行する場合があります。データベースロックは、クラスターノードが同時に起動する際に起動アクションが相互に競合するのを防ぎます。

このロックの最大タイムアウトは 900 秒です。ノードがタイムアウトを超えてロックを待機すると、起動は失敗します。デフォルト値を変更する必要はほぼありませんが、変更する場合は次のコマンドを入力します。

bin/kc.[sh|bat] start --spi-dblock-jpa-lock-wait-timeout 900

Red Hat build of Keycloak は、デフォルトで XA 以外のトランザクションと適切なデータベースドライバーを使用します。

ドライバーが提供する XA トランザクションサポートを使用する場合は、次のコマンドを入力します。

bin/kc.[sh|bat] build --db=<vendor> --transaction-xa-enabled=true

Red Hat build of Keycloak は、ベンダーに適した JDBC ドライバーを自動的に選択します。

XA リカバリーはデフォルトで有効になっており、ファイルシステムロケーション KEYCLOAK_HOME/data/transaction-logs を使用してトランザクションログを保存します。

JPA migrationStrategy (手動/更新/検証) を設定するには、次のように JPA プロバイダーを設定する必要があります。

bin/kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-strategy=manual

DB 初期化用の SQL ファイルも取得する場合は、次の SPI initializeEmpty (true/false) を追加する必要があります。

bin/kc.[sh|bat] start --spi-connections-jpa-quarkus-initialize-empty=false

同様に、migrationExport が特定のファイルと場所を指すようにします。

bin/kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-export=<path>/<file.sql>

詳細は、データベースの移行 に関するドキュメントを参照してください。

start コマンドを使用して Red Hat build of Keycloak を実稼働モードで開始すると、キャッシュが有効になり、ネットワーク上の Red Hat build of Keycloak ノードがすべて検出されます。

デフォルトでは、キャッシュは TCP トランスポートに基づく jdbc-ping スタックを使用し、設定されたデータベースを使用してクラスターに参加するノードを追跡します。この章で後述するとおり、Red Hat build of Keycloak では、事前定義されたデフォルトのトランスポートスタックのセットから選択することも、独自のカスタムスタックを定義することもできます。

分散 Infinispan キャッシュを明示的に有効にするには、次のコマンドを入力します。

bin/kc.[sh|bat] start --cache=ispn

start-dev コマンドを使用して Red Hat build of Keycloak を開発モードで開始すると、Red Hat build of Keycloak はローカルキャッシュのみを使用し、分散キャッシュは --cache=local オプションを暗黙的に設定することによって完全に無効になります。local キャッシュモードは、開発目的およびテスト目的に限定されています。

Red Hat build of Keycloak は、conf/cache-ispn.xml に置かれた適切なデフォルトを含むキャッシュ設定ファイルを提供します。

キャッシュ設定は通常の {infinispan_configuring_docs}[Infinispan 設定ファイル] です。

次の表は、Red Hat build of Keycloak が使用する特定のキャッシュの概要を示しています。これらのキャッシュは、conf/cache-ispn.xml で設定します。

bin/kc.[sh|bat] start --cache-config-file=my-cache-file.xml

トランスポートスタックにより、クラスター内の Red Hat build of Keycloak ノードが確実に信頼性の高い方法で通信できるようになります。Red Hat build of Keycloak は、幅広いトランスポートスタックをサポートしています。

特定のキャッシュスタックを適用するには、次のコマンドを入力します。

bin/kc.[sh|bat] start --cache-stack=<stack>

分散キャッシュが有効な場合、デフォルトのスタックは jdbc-ping に設定され、これは Red Hat build of Keycloak の 26.x リリースストリームのデフォルト設定と下位互換性があります。

TLS を使用した暗号化は、TCP ベースのトランスポートスタックでデフォルトで有効になっており、これがデフォルトの設定でもあります。TCP ベースのトランスポートスタックを使用している限り、追加の CLI オプションやキャッシュ XML の変更は必要ありません。

TLS を有効にすると、Red Hat build of Keycloak は接続を保護するために自己署名 RSA 2048 ビット証明書を自動生成し、TLS 1.3 を使用して通信を保護します。キーと証明書はデータベースに保存されるため、すべてのノードで使用できます。デフォルトでは、証明書の有効期間は 60 日間で、30 日ごとに実行中にローテーションされます。これを変更するには、オプション cache-embedded-mtls-rotation-interval-days を使用します。

Red Hat build of Keycloak クラスタリングを正常に実行するには、いくつかのネットワークポートを開く必要があります。以下の表では jdbc-ping スタック用に開く必要がある TCP ポートと、ポートを通過するトラフィックの説明を紹介しています。

正常な Red Hat build of Keycloak クラスタリングを確保するには、ネットワークポートを、クラスターの他のすべてのノードからアクセス可能なインターフェイスにバインドする必要があります。

デフォルトでは、192.168.0.0/16 または 10.0.0.0/8 のアドレス範囲から、サイトローカル (ルーティング不可能な) IP アドレスが選択されます。

アドレスをオーバーライドするには、jgroups.bind.address プロパティーを設定します。

IPv6 のみを設定し、Red Hat build of Keycloak でバインドアドレスを自動的に選択するには、次の設定を使用します。

export JAVA_OPTS_APPEND="-Djava.net.preferIPv4Stack=false -Djava.net.preferIPv6Addresses=true"

ファイアウォールの背後やコンテナー内など、異なるネットワーク上で Red Hat build of Keycloak インスタンスを実行すると、各インスタンスはローカル IP アドレスで相互にアクセスできなくなります。このような場合は、ローカル IP アドレスへのポート転送ルール (「仮想サーバー」と呼ばれることもあります) を設定します。

ポート転送を使用する場合は、各ノードが外部アドレスを他のノードに正しくアドバタイズできるように、次のプロパティーを使用します。

メトリクスが有効になっている場合、キャッシュからのメトリクスは自動的に公開されます。

キャッシュメトリクスのヒストグラムを有効にするには、cache-metrics-histograms-enabled を true に設定します。これらのメトリクスはレイテンシー分布に関するより詳細な情報を提供しますが、収集するとパフォーマンスに影響する可能性があるため、すでに飽和状態のシステムでこれらを有効にする場合は注意が必要です。

bin/kc.[sh|bat] start --metrics-enabled=true --cache-metrics-histograms-enabled=true

メトリクスを有効にする方法の詳細は、メトリクスによる分析情報の取得 を参照してください。

Red Hat build of Keycloak が TLS を使用して送信要求を実行できるように Red Hat build of Keycloak のトラストストアを設定する方法は、信頼済み証明書の設定 を参照してください。

Red Hat build of Keycloak が送信通信に使用する HTTP クライアントは、高度な設定が可能です。Red Hat build of Keycloak の送信 HTTP クライアントを設定するには、次のコマンドを入力します。

bin/kc.[sh|bat] start --spi-connections-http-client-default-<configurationoption>=<value>

コマンドのオプションは次のとおりです。

プロキシーを使用するように送信要求を設定するには、標準プロキシー環境変数である HTTP_PROXY、HTTPS_PROXY、NO_PROXY を使用してプロキシーマッピングを設定します。

環境変数は小文字または大文字にすることができます。小文字が優先されます。たとえば、HTTP_PROXY と http_proxy の両方を定義した場合、http_proxy が使用されます。

HTTPS_PROXY=https://www-proxy.acme.com:8080
NO_PROXY=google.com,login.facebook.com

この例では、次のような結果になります。

プロキシーマッピングに環境変数を使用する代わりに、Red Hat build of Keycloak が送信する送信要求の proxy-mappings のコンマ区切りリストを設定できます。proxy-mapping は、hostname-pattern;proxy-uri 形式を使用する、正規表現ベースのホスト名パターンとプロキシー URI で構成されます。

たとえば、次の正規表現があります。

.*\.(google|googleapis)\.com

次のコマンドを入力して、正規表現ベースのホスト名パターンを適用します。

bin/kc.[sh|bat] start --spi-connections-http-client-default-proxy-mappings='.*\\.(google|googleapis)\\.com;http://www-proxy.acme.com:8080'

マイクロプロファイル設定はマッピングの配列を解析するために使用されるため、バックスラッシュ文字 \ は再度エスケープされます。

送信 HTTP 要求を決定するために、以下が実行されます。

プロキシーサーバーに認証が必要な場合は、username:password@ 形式でプロキシーユーザーの認証情報を含めます。以下に例を示します。

.*\.(google|googleapis)\.com;http://proxyuser:password@www-proxy.acme.com:8080

# All requests to Google APIs use http://www-proxy.acme.com:8080 as proxy
.*\.(google|googleapis)\.com;http://www-proxy.acme.com:8080

# All requests to internal systems use no proxy
.*\.acme\.com;NO_PROXY

# All other requests use http://fallback:8080 as proxy
.*;http://fallback:8080

この例では、以下が実行されます。

既存の Java デフォルトトラストストア証明書は、常に信頼されます。追加の証明書が必要な場合 (JRE によって認識されない自己署名認証局または内部認証局がある場合など) は、それを conf/truststores ディレクトリーまたはサブディレクトリーに追加することができます。証明書は、PEM ファイル、または拡張子が .p12、.pfx、または .pkcs12 の PKCS12 ファイル内にある場合があります。PKCS12 の場合、証明書が暗号化されていない必要があります。つまり、パスワードは必要ありません。

別のパスが必要な場合は、--truststore-paths オプションを使用して、PEM または PKCS12 ファイルが配置されている追加のファイルまたはディレクトリーを指定します。パスは、Red Hat build of Keycloak を起動した場所に対する相対パスであるため、代わりに絶対パスを使用することを推奨します。ディレクトリーが指定されている場合、そのディレクトリでトラストストアファイルが再帰的にスキャンされます。

該当するすべての証明書を追加すると、トラストストアは、javax.net.ssl プロパティーを介してシステムのデフォルトのトラストストアとして、また Red Hat build of Keycloak 内部で使用するデフォルトのトラストストアとして使用されます。

以下に例を示します。

bin/kc.[sh|bat] start --truststore-paths=/opt/truststore/myTrustStore.pfx,/opt/other-truststore/myOtherTrustStore.pem

独自の javax.net.ssl トラストストアシステムプロパティーを直接設定することも可能ですが、代わりに --truststore-paths を使用することを推奨します。

tls-hostname-verifier プロパティーを使用して、TLS 接続によるホスト名の検証方法を調整できます。

mTLS を使用した認証は、デフォルトで無効になっています。Red Hat build of Keycloak がサーバーであり、Red Hat build of Keycloak エンドポイントに対する要求からの証明書を検証する必要がある場合に mTLS 証明書の処理を有効にするには、トラストストアに適切な証明書を配置し、次のコマンドを使用して mTLS を有効にします。

bin/kc.[sh|bat] start --https-client-auth=<none|request|required>

required 値を使用すると、Red Hat build of Keycloak は常に証明書を求めるようにセットアップされ、要求に証明書が提供されない場合は失敗します。値を request に設定すると、Red Hat build of Keycloak は証明書がない要求も受け入れ、証明書が存在する場合にのみ証明書の正確性を検証します。

デフォルトでは、Red Hat build of Keycloak はシステムトラストストアを使用して証明書を検証します。詳細は、信頼できる証明書の設定 を参照してください。

mTLS 専用のトラストストアを使用する必要がある場合は、次のコマンドを実行してこのトラストストアのロケーションを設定できます。

bin/kc.[sh|bat] start --https-trust-store-file=/path/to/file --https-trust-store-password=<value>

トラストストアで認識されるファイル拡張子:

トラストストアにファイルタイプに一致する拡張子がない場合は、https-key-store-type オプションも設定する必要があります。

サポートされている一部の機能とすべてのプレビュー機能は、デフォルトで無効になっています。機能を有効にするには、次のコマンドを入力します。

bin/kc.[sh|bat] build --features="<name>[,<name>]"

たとえば、docker と token-exchange を有効にするには、次のコマンドを入力します。

bin/kc.[sh|bat] build --features="docker,token-exchange"

すべてのプレビュー機能を有効にするには、次のコマンドを入力します。

bin/kc.[sh|bat] build --features="preview"

有効な機能には、バージョン管理されているものも、バージョン管理されていないものもあります。バージョン付きの機能名 (例: feature:v1) を使用すると、その機能バージョンがランタイム内に存在する限り有効になります。代わりにバージョンなしの名前 (例: feature) を使用すると、サポートされる特定の機能バージョンの選択が、次の優先順位によってリリースごとに変わる可能性があります。

デフォルトで有効になっている機能を無効にするには、次のコマンドを入力します。

bin/kc.[sh|bat] build --features-disabled="<name>[,<name>]"

たとえば、impersonation を無効にするには、次のコマンドを入力します。

bin/kc.[sh|bat] build --features-disabled="impersonation"

ある機能を features-disabled リストと features リストの両方に指定することはできません。

機能を無効にすると、その機能のすべてのバージョンが無効になります。

次のリストには、デフォルトで有効になっているサポート対象機能が含まれています。これらの機能は、必要がない場合は無効にできます。

プレビュー機能はデフォルトでは無効になっており、実稼働環境での使用は推奨されません。これらの機能は、今後のリリースで変更または削除される可能性があります。

次のリストには、今後のリリースで削除される予定の非推奨機能が含まれています。これらの機能は、デフォルトで無効になっています。

プロバイダーは、特定の設定形式を使用して設定できます。形式は、以下で構成されています。

spi-<spi-id>-<provider-id>-<property>=<value>

<spi-id> は、設定する SPI の名前です。

<provider-id> は、設定するプロバイダーの ID です。これは、対応するプロバイダーファクトリー実装に設定された ID です。

<property> は、特定のプロバイダーに設定するプロパティーの実際の名前です。

これらの名前 (spi、プロバイダー、プロパティー) はすべて小文字とし、myKeycloakProvider のようなキャメルケースの名前は、my-keycloak-provider のように大文字の前にダッシュ (-) が必要です。

たとえば HttpClientSpi SPI の場合、SPI の名前は connectionsHttpClient で、使用可能なプロバイダー実装の 1 つは、default という名前です。connectionPoolSize プロパティーを設定するには、次のように設定オプションを使用します。

spi-connections-http-client-default-connection-pool-size=10

プロバイダー設定オプションは、サーバーの起動時に指定します。Red Hat build of Keycloak の設定 のオプションで、サポートされているすべての設定ソースと形式を参照してください。たとえば、コマンドラインオプションを使用して以下のように指定します。

bin/kc.[sh|bat] start --spi-connections-http-client-default-connection-pool-size=10

SPI によっては、複数のプロバイダー実装が同時に存在することも可能ですが、実行時に使用されるのはそのうちの 1 つだけです。これらの SPI の場合、特定のプロバイダーがランタイムにアクティブになり使用される主要な実装になります。

プロバイダーを単一のプロバイダーとして設定するには、次のように build コマンドを実行する必要があります。

bin/kc.[sh|bat] build --spi-email-template-provider=mycustomprovider

SPI に応じて、複数のプロバイダー実装が共存でき、デフォルトでは 1 つが使用されます。これらの SPI の場合、特定のプロバイダーが要求されない限り、特定のプロバイダーがデフォルトの実装として選択されます。

デフォルトのプロバイダーを決定するために、次のロジックが使用されます。

プロバイダーをデフォルトプロバイダーとして設定するには、次のように build コマンドを実行する必要があります。

bin/kc.[sh|bat] build --spi-password-hashing-provider-default=mycustomprovider

プロバイダーを有効または無効にするには、次のように build コマンドを実行する必要があります。

bin/kc.[sh|bat] build --spi-email-template-mycustomprovider-enabled=true

プロバイダーを無効にするには、同じコマンドを使用し、enabled プロパティーを false に設定します。

カスタムプロバイダーは、Java アーカイブ (JAR) ファイルにパッケージ化して、ディストリビューションの providers ディレクトリーにコピーする必要があります。その後、build コマンドを実行して、サーバーのプロバイダーレジストリーを JAR ファイルの実装で更新する必要があります。

この手順は、サーバーランタイムを最適化するために必要です。そうすることで、サーバーの起動時や実行時にプロバイダーを検出するのではなく、事前にすべてのプロバイダーが既知になるようになります。

プロバイダーをアンインストールするには、providers ディレクトリーから JAR ファイルを削除し、build コマンドを再度実行する必要があります。

プロバイダーを実装する場合、サーバーディストリビューションからは利用できないサードパーティーの依存関係を使用する必要があることもあります。

この場合、追加の依存関係を providers ディレクトリーにコピーし、build コマンドを実行する必要があります。これを実行すると、サーバーはこれらの追加の依存関係を、それに依存するプロバイダーが実行時に使用できるようにします。

ロギングは、Red Hat build of Keycloak でカテゴリーごとに行われます。ロギングは、ルートログレベル、または org.hibernate や org.keycloak などのより具体的なカテゴリーで設定できます。特定のログハンドラーごとにログレベルをカスタマイズすることも可能です。

この章では、ロギングの設定方法を説明します。

bin/kc.[sh|bat] start --log-level=<root-level>

bin/kc.[sh|bat] start --log-level="<root-level>,<org.category1>:<org.category1-level>"

bin/kc.[sh|bat] start --log-level="INFO,org.hibernate:debug,org.hibernate.hql.internal.ast:info"

bin/kc.[sh|bat] start --log-level="INFO,org.hibernate:debug"

bin/kc.[sh|bat] start --log-level="INFO,org.hibernate:debug" --log-level-org.keycloak=trace