サーバー設定ガイド

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

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

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

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

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

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

export KC_DB_URL_HOST=mykeycloakdb

export KC_DB_URL_HOST=mykeycloakdb

db-url-host=mykeycloakdb

db-url-host=mykeycloakdb

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

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

db-url-host=${MY_DB_HOST}

db-url-host=${MY_DB_HOST}

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

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

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

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

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

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

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

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

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

bin/kc.[sh|bat] start

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 <build-options>

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

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

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

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

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

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 上で実行されます。これらは、クラスター化されている場合に高い信頼性と可用性を提供します。クラスターにデプロイされている場合は、組み込み Infinispan サーバーの通信を保護する必要があります。この通信を保護するには、認証と暗号化を有効にするか、クラスター通信に使用されるネットワークを分離します。

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

システムプロパティーである 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"

export JAVA_OPTS_APPEND="-Djava.net.preferIPv4Stack=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 --bootstrap-admin-username tmpadm --bootstrap-admin-password pass

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

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

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

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

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

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>

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}

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

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

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

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

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

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

bin/kc.[sh|bat] bootstrap-admin user --username tmpadm --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

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>

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>

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

zip ファイルからインストールする場合、デフォルトで rhbk-26.0.15 のインストール 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 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
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"]

FROM registry.redhat.io/rhbk/keycloak-rhel9:26 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
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 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

# 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 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
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 /

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 /

podman build . -t mykeycloak

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

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

デフォルトで、サーバーはポート 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

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 \
        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 \
        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 \
        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>

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 \
        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

# 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 \
        start-dev --import-realm

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 \
        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 \
        start-dev

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 \
        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

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

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

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

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>]

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

TLSv1.2 も許可するには、kc.sh start --https-protocols=TLSv1.3,TLSv1.2 などのコマンドを使用します。

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

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

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

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

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

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

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

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-strict false --proxy-headers forwarded

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

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 --proxy-headers xforwarded

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

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

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 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-backchannel-dynamic true

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

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

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 は、proxy-headers オプションに基づいてリバースプロキシーヘッダーを解析します。このオプションは、次のいくつかの値を受け入れます。

以下に例を示します。

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

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

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

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 に設定すると、返されるリモートアドレスは実際の接続クライアントからのアドレスになります。

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

以下に例を示します。

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

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] 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

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 の一部として出荷されます。

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

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

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

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

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

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

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

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

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

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

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

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>

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 ノードがすべて検出されます。

デフォルトでは、キャッシュは UDP トランスポートスタックを使用するため、UDP に基づく IP マルチキャストトランスポートを使用してノードが検出されます。ほとんどの実稼働環境では、UDP に代わるより優れた検出手段が利用可能です。この章で後述するとおり、Red Hat build of Keycloak では、事前定義されたデフォルトのトランスポートスタックのセットから選択することも、独自のカスタムスタックを定義することもできます。

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

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

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 に置かれた適切なデフォルトを含むキャッシュ設定ファイルを提供します。

キャッシュ設定は、通常の nfinispan configuration file です。

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

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

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

トランスポートスタックにより、クラスター内の分散キャッシュノードは信頼できる方法で通信できます。Red Hat build of Keycloak は、幅広いトランスポートスタックをサポートしています。

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

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

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

分散キャッシュが有効な場合、デフォルトのスタックが udp に設定されます。

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

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

<jgroups>
    <stack name="my-encrypt-udp" extends="udp">
        <SSL_KEY_EXCHANGE keystore_name="server.jks"
            keystore_password="password"
            stack.combine="INSERT_AFTER"
            stack.position="VERIFY_SUSPECT2"/>
        <ASYM_ENCRYPT asym_keylength="2048"
            asym_algorithm="RSA"
            change_key_on_coord_leave = "false"
            change_key_on_leave = "false"
            use_external_key_exchange = "true"
            stack.combine="INSERT_BEFORE"
            stack.position="pbcast.NAKACK2"/>
    </stack>
</jgroups>

<cache-container name="keycloak">
    <transport lock-timeout="60000" stack="my-encrypt-udp"/>
    ...
</cache-container>

<jgroups>
    <stack name="my-encrypt-udp" extends="udp">
        <SSL_KEY_EXCHANGE keystore_name="server.jks"
            keystore_password="password"
            stack.combine="INSERT_AFTER"
            stack.position="VERIFY_SUSPECT2"/>
        <ASYM_ENCRYPT asym_keylength="2048"
            asym_algorithm="RSA"
            change_key_on_coord_leave = "false"
            change_key_on_leave = "false"
            use_external_key_exchange = "true"
            stack.combine="INSERT_BEFORE"
            stack.position="pbcast.NAKACK2"/>
    </stack>
</jgroups>

<cache-container name="keycloak">
    <transport lock-timeout="60000" stack="my-encrypt-udp"/>
    ...
</cache-container>

<jgroups>
    <stack name="tcpping" extends="tcp">
        <TCPPING initial_hosts="192.168.1.1[7800],192.168.1.2[7800]" 
               stack.combine="REPLACE"
               stack.position="MPING"/>
    </stack>
</jgroups>

<cache-container name="keycloak">
    <transport lock-timeout="60000" stack="tcpping"/>
    ...
</cache-container>

<jgroups>
    <stack name="tcpping" extends="tcp">
        <TCPPING initial_hosts="192.168.1.1[7800],192.168.1.2[7800]" 

               stack.combine="REPLACE"
               stack.position="MPING"/>
    </stack>
</jgroups>

<cache-container name="keycloak">
    <transport lock-timeout="60000" stack="tcpping"/>
    ...
</cache-container>

Red Hat build of Keycloak クラスタリングを正常に実行するには、2 つのネットワークポートを開く必要があります。

Red Hat build of Keycloak は、UDP ベースおよび TCP ベースのスタックでのデータ転送に jgroups.bind.port を使用します。

障害検出のために、Red Hat build of Keycloak はデフォルトで 50000 に設定されている最初のポートを基準として jgroups.fd.port-offset のオフセットにある別の TCP ベースのポートを使用します。jgroups.bind.port プロパティーが 7800 に設定されている場合、57800 で TCP ポートが開きます。

現行の Infinispan キャッシュ実装は、RBAC、ACL、トランスポートスタック暗号化などのさまざまなセキュリティー対策により保護されているはずです。

JGroups は、Red Hat build of Keycloak サーバー間のすべての通信を処理し、TCP 通信用の Java SSL ソケットをサポートします。Red Hat build of Keycloak は、CLI オプションを使用して TLS 通信を設定します。カスタマイズした JGroups スタックを作成したり、キャッシュ XML ファイルを変更したりする必要はありません。

TLS を有効にするには、cache-embedded-mtls-enabled を true に設定する必要があります。使用する証明書を含むキーストアが必要です。cache-embedded-mtls-key-store-file でキーストアへのパスを設定し、cache-embedded-mtls-key-store-password でそれを復号するためのパスワードを設定します。トラストストアに、接続を受け入れるための有効な証明書を格納します。トラストストアは、cache-embedded-mtls-trust-store-file (トラストストアへのパス) と cache-embedded-mtls-trust-store-password (それを復号するためのパスワード) を使用して設定できます。不正アクセスを制限するには、各 Red Hat build of Keycloak に自己署名証明書を使用します。

UDP または TCP_NIO2 を使用した JGroups スタックの場合、プロトコルスタックの設定方法について、JGroups 暗号化ドキュメント を参照してください。

キャッシュ通信の保護の詳細は、Infinispan Security Guide を参照してください。

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

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

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

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

メトリクスを有効にする方法の詳細は、Red Hat build of Keycloak のメトリクスの有効化 を参照してください。

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>

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