Menu Close
Settings Close

Language and Page Formatting Options

サーバーインストールおよび設定ガイド

Red Hat Single Sign-On 7.6

Red Hat Single Sign-On 7.6 向け

概要

本ガイドは、Red Hat Single Sign-On 7.6 をインストールおよび設定するための情報で構成されています。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、今後の複数のリリースで段階的に用語の置き換えを実施して参ります。詳細は、弊社 の CTO、Chris Wright のメッセージを参照してください。

第1章 ガイドの概要

本ガイドでは、Red Hat Single Sign-On サーバーを初めて起動する前に完了が必要な手順を説明します。Red Hat Single Sign-On をテストするだけの場合は、独自の組み込みのローカル専用データベースを使用して、すぐに実行することができます。本番環境で実行される実際のデプロイメントでは、実行時のサーバー設定の管理方法 (スタンドアロンまたはドメインモード)、Red Hat Single Sign-On ストレージ用の共有データベースの設定方法、暗号化および HTTPS の設定方法、そして最後に Red Hat Single Sign-On をクラスターで実行する設定方法を決定する必要があります。本書では、サーバーをデプロイする前に実行する必要のある起動前の決定とセットアップのあらゆる側面について説明します。

特に注意すべき点の 1 つは、Red Hat Single Sign-On が JBoss EAP Application Server から派生していることです。Red Hat Single Sign-On の設定の多くの側面は、JBoss EAP 設定要素を中心に行われています。本書では、さらなる詳細の参照先として、外部のドキュメントを提示している場合が多々あります。

第2章 ソフトウェアのインストール

Red Hat Single Sign-On をインストールするには、ZIP ファイルをダウンロードして解凍するか、RPM を使用します。本章では、システム要件とディレクトリー構造を確認します。

2.1. インストールの要件

以下は Red Hat Single Sign-On サーバーをインストールするための前提条件です。

  • Java を実行する任意のオペレーティングシステム上で実行可能
  • Java 8 JRE または Java 11 JRE
  • zip または gzip および tar
  • 512M 以上の RAM
  • 1G 以上のディスク領域
  • PostgreSQL、MySQL、Oracle などの共有外部データベース。クラスターで実行する場合、Red Hat Single Sign-On には外部共有データベースが必要です。詳細は、本書の「データベースの設定」セクションを参照してください。
  • マシンでのネットワークマルチキャストのサポート(クラスターで実行する必要がある場合)。Red Hat Single Sign-On は、マルチキャストなしでクラスター化できますが、これには多数の設定変更が必要です。詳細は、本書の「クラスタリング」セクションを参照してください。
  • Linuxでは、/dev/random の使用がセキュリティポリシーで義務付けられていない限り、利用可能なエントロピーの不足による Red Hat Single Sign-On のハングを防ぐために、ランダムデータのソースとして /dev/urandom を使用することをお勧めします。これを行うには、Oracle JDK 8 および OpenJDK 8 で、システムの起動時に java.security.egd システムプロパティーを file:/dev/urandom に設定します。

2.2. ZIP ファイルからの RH-SSO のインストール

Red Hat Single Sign-On サーバーのダウンロード ZIP ファイルには、Red Hat Single Sign-On サーバーを実行するためのスクリプトとバイナリーが含まれています。最初に 7.6 サーバーをインストールし、続いて 7.6.0 サーバーパッチをインストールします。

手順

  1. Red Hat カスタマーポータル に移動します。
  2. Red Hat Single Sign-On 7.6 サーバーをダウンロードします。
  3. unzip、tar、Expand-Archive などの適切な unzip ユーティリティーを使用して ZIP ファイルを展開します。
  4. Red Hat カスタマーポータル に戻ります。
  5. Patches タブをクリックします。
  6. Red Hat Single Sign-On 7.6.0 サーバーパッチをダウンロードします。
  7. 選択したディレクトリーにダウンロードしたファイルを配置します。
  8. JBoss EAP の bin ディレクトリーに移動します。
  9. JBoss EAP コマンドラインインターフェースを起動します。

    Linux/Unix

    $ jboss-cli.sh

    Windows

    > jboss-cli.bat

  10. パッチを適用します。

    $ patch apply <path-to-zip>/rh-sso-7.6.0-patch.zip

関連資料

パッチ適用の詳細は、「 ZIP/インストーラーインストールのパッチ適用」を 参照してください。

2.3. RPM からの RH-SSO のインストール

注記

Red Hat Enterprise Linux 7 および 8 では、チャンネル という用語はリポジトリーという用語に置き換えられました。これらの手順では、リポジトリーという用語のみが使用されています。

RPM から RH-SSO をインストールする前に、JBoss EAP 7.4 リポジトリーと RH-SSO 7.6 リポジトリーの両方をサブスクライブする必要があります。

注記

EAP RPM へのアップグレードを引き続き受信することはできませんが、RH-SSO の更新の受信を停止することはできません。

2.3.1. JBoss EAP 7.4 リポジトリーへのサブスクライブ

前提条件

  1. Red Hat Subscription Manager を使用して、Red Hat Enterprise Linux システムがお使いのアカウントに登録されている必要があります。詳細は、Red Hat Subscription Management のドキュメント を参照してください。
  2. すでに別の JBoss EAP リポジトリーにサブスクライブしている場合は、最初にそのリポジトリーからサブスクライブを解除する必要があります。

Red Hat Enterprise Linux 6、7 の場合: Red Hat Subscription Manager を使用して、以下のコマンドで JBoss EAP 7.4 リポジトリーにサブスクライブします。お使いの Red Hat Enterprise Linux のバージョンに応じて、<RHEL_VERSION> を 6 または 7 に置き換えてください。

subscription-manager repos --enable=jb-eap-7.4-for-rhel-<RHEL_VERSION>-server-rpms --enable=rhel-<RHEL_VERSION>-server-rpms

Red Hat Enterprise Linux 8 の場合: Red Hat Subscription Manager を使用して、以下のコマンドで JBoss EAP 7.4 リポジトリーにサブスクライブします。

subscription-manager repos --enable=jb-eap-7.4-for-rhel-8-x86_64-rpms --enable=rhel-8-for-x86_64-baseos-rpms --enable=rhel-8-for-x86_64-appstream-rpms

2.3.2. RH-SSO 7.6 リポジトリーへのサブスクライブおよび RH-SSO 7.6 のインストール

前提条件

  1. Red Hat Subscription Manager を使用して、Red Hat Enterprise Linux システムがお使いのアカウントに登録されている必要があります。詳細は、Red Hat Subscription Management のドキュメント を参照してください。
  2. JBoss EAP 7.4 リポジトリーにサブスクライブしていることを確認してください。詳細は、「JBoss EAP 7.4 リポジトリーへのサブスクライブ」を参照してください。

手順

  1. Red Hat Enterprise Linux 6、7 の場合: Red Hat Subscription Manager の使用は、以下のコマンドを使用して RH-SSO 7.6 リポジトリーにサブスクライブします。お使いの Red Hat Enterprise Linux のバージョンに応じて、<RHEL_VERSION> を 6 または 7 に置き換えてください。

    subscription-manager repos --enable=rh-sso-7.6-for-rhel-<RHEL-VERSION>-server-rpms
  2. Red Hat Enterprise Linux 8 の場合: Red Hat Subscription Manager を使用している場合は、以下のコマンドを使用して RH-SSO 7.6 リポジトリーにサブスクライブします。

    subscription-manager repos --enable=rh-sso-7.6-for-rhel-8-x86_64-rpms
  3. Red Hat Enterprise Linux 6、7 の場合: 以下のコマンドを使用して、サブスクライブしている RH-SSO 7.6 リポジトリーから RH-SSO をインストールします。

    yum groupinstall rh-sso7
  4. Red Hat Enterprise Linux 8 の場合: 以下のコマンドを使用して、サブスクライブしている RH-SSO 7.6 リポジトリーから RH-SSO をインストールします。

    dnf groupinstall rh-sso7

インストールが完了しました。RPM インストールのデフォルトの RH-SSO_HOME パスは /opt/rh/rh-sso7/root/usr/share/keycloak です。

関連資料

Red Hat Single Sign-On の 7.6.0 パッチをインストールする方法は、「 RPM patching 」を参照してください。

2.4. 重要なディレクトリー

以下は、サーバーディストリビューションのいくつかの重要なディレクトリーです。

bin/
これには、サーバーを起動するスクリプト、またはサーバー上でその他の管理アクションを実行するスクリプトが含まれます。
domain/
これには、Red Hat Single Sign-On を ドメインモード で実行する場合の設定ファイルと作業ディレクトリーが含まれます。
modules/
これらはすべて、サーバーが使用する Java ライブラリーです。
standalone/
これには、スタンドアロンモード で Red Hat Single Sign-On を実行する場合の設定ファイルと作業ディレクトリーが含まれます。
standalone/deployments/
Red Hat Single Sign-On の拡張機能を作成している場合は、ここに拡張機能を配置できます。詳細は、『サーバー 開発者ガイド』 を参照してください。
themes/
このディレクトリーには、サーバーによって表示される UI 画面を表示するために使用されるすべての html、スタイルシート、JavaScript ファイル、およびイメージが含まれます。ここでは、既存のテーマを変更したり、独自のテーマを作成したりできます。詳細は、『サーバー 開発者ガイド』 を参照してください。

第3章 操作モードの使用

実稼働環境で Red Hat Single Sign-On をデプロイする前に、使用する操作モードを決定する必要があります。

  • クラスター内で Red Hat Single Sign-On を実行しますか?
  • サーバー設定を一元管理する方法が必要ですか?

操作モードを選択すると、データベースの設定方法、キャッシュの設定方法、およびサーバーの起動方法に影響を及ぼします。

ヒント

Red Hat Single Sign-On は、JBoss EAP Application Server 上に構築されています。本ガイドでは、特定モードでのデプロイメントの基本についてのみ説明します。これに関する特定の情報が必要な場合は、JBoss EAP の『設定ガイド』を参照してください。

3.1. スタンドアロンモードの使用

スタンドアロン操作モードは、1 つの Red Hat Single Sign-On サーバーインスタンスのみを実行する場合に便利です。クラスター化されたデプロイメントには使用できず、すべてのキャッシュは分散されず、ローカル専用となります。単一障害点が発生するため、本番環境でスタンドアロンモードを使用することはお勧めしません。スタンドアロンモードサーバーがダウンした場合は、ユーザーはログインできなくなります。このモードは、Red Hat Single Sign-On の機能をテストしたり、試したりする場合にのみ便利です。

3.1.1. スタンドアロンモードでの起動

スタンドアロンモードでサーバーを実行する場合は、オペレーティングシステムに応じて、サーバーを起動するために特定のスクリプトが必要です。このスクリプトは、サーバーディストリビューションの bin/ ディレクトリーにあります。

スタンドアロン起動スクリプト

standalone boot files

サーバーを起動するには、次のコマンドを実行します。

Linux/Unix

$ .../bin/standalone.sh

Windows

> ...\bin\standalone.bat

3.1.2. スタンドアロン設定

このガイドの大部分では、Red Hat Single Sign-On のインフラストラクチャーレベルの側面を設定する方法について説明します。これらの側面は、Red Hat Single Sign-On が派生したアプリケーションサーバーに固有の設定ファイルで設定されます。スタンドアロン操作モードでは、このファイルは …​/standalone/configuration/standalone.xml にあります。このファイルは、Red Hat Single Sign-On コンポーネントに固有のインフラストラクチャー以外のレベルの設定にも使用されます。

スタンドアロン設定ファイル

standalone config file

警告

サーバーの実行中にこのファイルに加える変更は適用されず、サーバーによって上書きされる場合もあります。代わりに、JBoss EAP のコマンドラインスクリプトまたは Web コンソールを使用します。詳細は、JBoss EAP の『設定ガイド』 を参照してください。

3.2. スタンドアロンクラスター化モードの使用

スタンドアロンクラスター化操作モードは、クラスター内で Red Hat Single Sign-On を実行する場合に適用します。このモードでは、サーバーインスタンスを実行する各マシンに Red Hat Single Sign-On ディストリビューションのコピーが必要です。このモードは、最初は簡単にデプロイできますが、非常に厄介となってくる場合があります。設定変更を行うには、各マシンの各ディストリビューションを変更します。大規模なクラスターの場合、このモードでは多大な時間がかかり、エラーが発生しやすくなります。

3.2.1. スタンドアロンクラスター化設定

ディストリビューションには、クラスター内で実行するための、ほとんどが事前設定されたアプリサーバー設定ファイルがあります。これには、ネットワーク、データベース、キャッシュ、検出用の特定のインフラストラクチャー設定がすべて含まれます。このファイルは …​/standalone/configuration/standalone-ha.xml にあります。この設定にはいくつか欠けているものがあります。共有データベース接続を設定せずに、クラスターで Red Hat Single Sign-On を実行することはできません。また、ある種のロードバランサーをクラスターの前にデプロイする必要もあります。本ガイドの「クラスタリング」および「データベース」セクションで、これらの項目について説明します。

スタンドアロン HA 設定

standalone ha config file

警告

サーバーの実行中にこのファイルに加える変更は適用されず、サーバーによって上書きされる場合もあります。代わりに、JBoss EAP のコマンドラインスクリプトまたは Web コンソールを使用します。詳細は、JBoss EAP の『設定ガイド』 を参照してください。

3.2.2. スタンドアロンクラスター化モードでの起動

スタンドアロンモードの場合と同じ起動スクリプトを使用して、Red Hat Single Sign-On を起動します。相違点は、追加のフラグを渡して HA 設定ファイルを参照することです。

スタンドアロンのクラスター化された起動スクリプト

standalone boot files

サーバーを起動するには、次のコマンドを実行します。

Linux/Unix

$ .../bin/standalone.sh --server-config=standalone-ha.xml

Windows

> ...\bin\standalone.bat --server-config=standalone-ha.xml

3.3. ドメインクラスター化されたモードの使用

ドメインモードは、サーバーの設定を一元管理して公開する方法です。

クラスターを標準モードで実行すると、クラスターのサイズが大きくなるにつれてすぐに深刻化する可能性があります。設定変更が必要になるたびに、クラスター内の各ノードで実行します。ドメインモードは、設定を格納および公開するための中心的な場所を提供することで、この問題を解決します。設定は非常に複雑となる場合がありますが、それだけの価値があると言えます。この機能は、Red Hat Single Sign-On の派生元である JBoss EAP Application Server に組み込まれています。

注記

このガイドでは、ドメインモードの基本について説明します。クラスターでドメインモードを設定する方法は、JBoss EAP の『設定ガイド』を参照してください。

ドメインモードで実行するための基本的な概念のいくつかを以下に示します。

ドメインコントローラー
ドメインコントローラーは、クラスター内の各ノードの一般的な設定を保存、管理、および公開するプロセスです。このプロセスは、クラスター内のノードが設定を取得するための中心となるポイントです。
ホストコントローラー
ホストコントローラーは、特定のマシン上のサーバーインスタンスを管理します。1 つ以上のサーバーインスタンスを実行するように設定します。ドメインコントローラーは、各マシンのホストコントローラーと対話してクラスターを管理することもできます。実行中のプロセスの数を減らすために、ドメインコントローラーは、実行されているマシンのホストコントローラーとしても機能します。
ドメインプロファイル
ドメインプロファイルは、サーバーが起動に使用できる名前付きの設定セットです。ドメインコントローラーは、異なるサーバーによって使用される複数のドメインプロファイルを定義できます。
サーバーグループ
サーバーグループとはサーバーの集合のことです。これらは 1 つとして管理および設定されます。ドメインプロファイルをサーバーグループに割り当てることができ、そのグループ内のすべてのサービスは、そのドメインプロファイルを設定として使用します。

ドメインモードでは、ドメインコントローラーがマスターノードで起動します。クラスターの設定は、ドメインコントローラーにあります。次に、クラスター内の各マシンでホストコントローラーが起動されます。各ホストコントローラーのデプロイメント設定は、そのマシンで開始する Red Hat Single Sign-On サーバーインスタンスの数を指定します。ホストコントローラーが起動すると、設定された数の Red Hat Single Sign-On サーバーインスタンスが起動します。これらのサーバーインスタンスは、ドメインコントローラーから設定をプルします。

注記

Microsoft Azure などの一部の環境では、ドメインモードは適用されません。詳細は、JBoss EAP のドキュメントを参照してください。

3.3.1. ドメイン設定

本ガイドのさまざまな章では、データベース、HTTP ネットワーク接続、キャッシュ、およびその他のインフラストラクチャー関連のものなど、さまざまな側面の設定について説明します。スタンドアロンモードは standalone.xml ファイルを使用してこれらを設定しますが、ドメインモードは …​/domain/configuration/domain.xml 設定ファイルを使用します。ここで、Red Hat Single Sign-On サーバーのドメインプロファイルとサーバーグループが定義されます。

domain.xml

domain file

警告

ドメインコントローラーの実行中にこのファイルに加える変更は適用されず、サーバーによって上書きされる場合もあります。代わりに、JBoss EAP のコマンドラインスクリプトまたは Web コンソールを使用します。詳細は、JBoss EAP の『設定ガイド』 を参照してください。

この domain.xml ファイルのいくつかの側面を見てみましょう。auth-server-standalone および auth-server-clustered profile XML ブロックは、設定の決定を一括して行う場所です。ここでは、ネットワーク接続、キャッシュ、データベース接続などを設定します。

auth-server プロファイル

    <profiles>
        <profile name="auth-server-standalone">
            ...
        </profile>
        <profile name="auth-server-clustered">
            ...
        </profile>

auth-server-standalone プロファイルは、クラスター化されていないセットアップです。auth-server-clustered プロファイルはクラスター化されたセットアップです。

スクロールダウンすると、さまざまな socket-binding-groups が定義されていることが確認できます。

socket-binding-groups

    <socket-binding-groups>
        <socket-binding-group name="standard-sockets" default-interface="public">
           ...
        </socket-binding-group>
        <socket-binding-group name="ha-sockets" default-interface="public">
           ...
        </socket-binding-group>
        <!-- load-balancer-sockets should be removed in production systems and replaced with a better software or hardware based one -->
        <socket-binding-group name="load-balancer-sockets" default-interface="public">
           ...
        </socket-binding-group>
    </socket-binding-groups>

この設定は、各 Red Hat Single Sign-On サーバーインスタンスで開かれる各種コネクターのデフォルトのポートマッピングを定義します。${…​} を含む値は、-D スイッチを使用してコマンドラインで上書きできる値です。つまり、以下のようになります。

$ domain.sh -Djboss.http.port=80

Red Hat Single Sign-On のサーバーグループの定義は、server-groups XML ブロックにあります。これは使用されるドメインプロファイル (default) と、ホストコントローラーがインスタンスの起動時に Java 仮想マシンのデフォルトブート引数の一部を指定します。また、socket-binding-group をサーバーグループにバインドします。

サーバーグループ

    <server-groups>
        <!-- load-balancer-group should be removed in production systems and replaced with a better software or hardware based one -->
        <server-group name="load-balancer-group" profile="load-balancer">
            <jvm name="default">
                <heap size="64m" max-size="512m"/>
            </jvm>
            <socket-binding-group ref="load-balancer-sockets"/>
        </server-group>
        <server-group name="auth-server-group" profile="auth-server-clustered">
            <jvm name="default">
                <heap size="64m" max-size="512m"/>
            </jvm>
            <socket-binding-group ref="ha-sockets"/>
        </server-group>
    </server-groups>

3.3.2. ホストコントローラーの設定

Red Hat Single Sign-On には、…​/domain/configuration/ ディレクトリーにある 2 つのホストコントローラー設定ファイル (host-master.xml および host-slave.xml) が同梱されています。host-master.xml は、ドメインコントローラー、ロードバランサー、および 1 つの Red Hat Single Sign-On サーバーインスタンスを起動するように設定されています。host-slave.xml は、ドメインコントローラーと通信し、1 つの Red Hat Single Sign-On サーバーインスタンスを起動するように設定されています。

注記

ロードバランサーは必須サービスではありません。これは、開発マシンでクラスタリングを簡単にテストできるようにするために存在します。実稼働環境で使用できますが、使用するハードウェアまたはソフトウェアベースのロードバランサーが異なる場合は、これを置き換えるオプションがあります。

ホストコントローラーの設定

host files

ロードバランサーサーバーインスタンスを無効にするには、host-master.xml を編集し、"load-balancer" エントリーをコメントアウトまたは削除します。

    <servers>
        <!-- remove or comment out next line -->
        <server name="load-balancer" group="loadbalancer-group"/>
        ...
    </servers>

このファイルについて注意すべきもう 1 つの興味深い点は、認証サーバーインスタンスの宣言です。これには、port-offset が設定されています。domain.xml socket-binding-group またはサーバーグループで定義されたネットワークポートには、port-offset の値が追加されます。このサンプルドメイン設定では、ロードバランサーサーバーが開かれているポートが起動した認証サーバーインスタンスと競合しないように、これを行います。

    <servers>
        ...
        <server name="server-one" group="auth-server-group" auto-start="true">
             <socket-bindings port-offset="150"/>
        </server>
    </servers>

3.3.3. サーバーインスタンスの作業ディレクトリー

ホストファイルで定義された各 Red Hat Single Sign-On サーバーインスタンスは、…​/domain/servers/{SERVER NAME} の下に作業ディレクトリーを作成します。追加の設定をそこに置くことができ、サーバーインスタンスが必要とする、または作成する一時ファイル、ログファイル、またはデータファイルもそこに配置されます。これらのサーバーディレクトリーごとの構造は、他の JBoss EAP の起動サーバーと同じようになります。

作業ディレクトリー

domain server dir

3.3.4. ドメインクラスター化されたモードの起動

ドメインモードでサーバーを実行する場合は、オペレーティングシステムに応じて、サーバーを起動するために特定のスクリプトを実行する必要があります。このスクリプトは、サーバーディストリビューションの bin/ ディレクトリーにあります。

ドメインブートスクリプト

domain boot files

サーバーを起動するには、次のコマンドを実行します。

Linux/Unix

$ .../bin/domain.sh --host-config=host-master.xml

Windows

> ...\bin\domain.bat --host-config=host-master.xml

ブートスクリプトを実行する場合は、--host-config スイッチから使用するホスト制御設定ファイルを渡す必要があります。

3.3.5. サンプルクラスター化ドメインを使用したテスト

サンプルの domain.xml 設定を使用して、ドライブのクラスタリングをテストできます。このサンプルドメインは、1 台のマシンで実行され、以下を起動することを目的としています。

  • ドメインコントローラー
  • HTTP ロードバランサー
  • 2 つの Red Hat Single Sign-On サーバーインスタンス

手順

  1. domain.sh スクリプトを 2 回実行して、2 つの別々のホストコントローラーを起動します。

    1 つ目は、ドメインコントローラー、HTTP ロードバランサー、および 1 つの Red Hat Single Sign-On 認証サーバーインスタンスを起動するマスターホストコントローラーです。2 つ目は、認証サーバーインスタンスのみを起動するスレーブホストコントローラーです。

  2. スレーブホストコントローラーを設定して、ドメインコントローラーとセキュアに通信できるようにします。以下の手順を実行します。

    これらの手順を実行しないと、スレーブホストはドメインコントローラーから集中設定を取得できません。

    1. サーバー管理ユーザーと、マスターおよびスレーブの間で共有されるシークレットを作成して、セキュアな接続を設定します。

      …/bin/add-user.sh スクリプトを実行します。

    2. スクリプトが追加するユーザーのタイプについて尋ねてきたら、Management User を選択します。

      この選択により、…/domain/configuration/host-slave.xml ファイルにカットアンドペーストするシークレットが生成されます。

      アプリケーションサーバー管理者の追加

      $ add-user.sh
       What type of user do you wish to add?
        a) Management User (mgmt-users.properties)
        b) Application User (application-users.properties)
       (a): a
       Enter the details of the new user to add.
       Using realm 'ManagementRealm' as discovered from the existing property files.
       Username : admin
       Password recommendations are listed below. To modify these restrictions edit the add-user.properties configuration file.
        - The password should not be one of the following restricted values {root, admin, administrator}
        - The password should contain at least 8 characters, 1 alphabetic character(s), 1 digit(s), 1 non-alphanumeric symbol(s)
        - The password should be different from the username
       Password :
       Re-enter Password :
       What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[ ]:
       About to add user 'admin' for realm 'ManagementRealm'
       Is this correct yes/no? yes
       Added user 'admin' to file '/.../standalone/configuration/mgmt-users.properties'
       Added user 'admin' to file '/.../domain/configuration/mgmt-users.properties'
       Added user 'admin' with groups to file '/.../standalone/configuration/mgmt-groups.properties'
       Added user 'admin' with groups to file '/.../domain/configuration/mgmt-groups.properties'
       Is this new user going to be used for one AS process to connect to another AS process?
       e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server EJB calls.
       yes/no? yes
       To represent the user add the following to the server-identities definition <secret value="bWdtdDEyMyE=" />

      注記

      add-user.sh スクリプトは、ユーザーを Red Hat Single Sign-On サーバーには追加せず、基礎となる JBoss Enterprise Application Platform に追加します。このスクリプトで使用および生成される認証情報は、デモンストレーションのみを目的としています。お使いのシステムで生成されたものを使用してください。

  3. 以下のように秘密の値を …​/domain/configuration/host-slave.xml ファイルにカットアンドペーストします。

         <management>
             <security-realms>
                 <security-realm name="ManagementRealm">
                     <server-identities>
                         <secret value="bWdtdDEyMyE="/>
                     </server-identities>
  4. 作成したユーザーの ユーザー名…​/domain/configuration/host-slave.xml ファイルに追加します。

         <remote security-realm="ManagementRealm" username="admin">
  5. 起動スクリプトを 2 回実行して、1 台の開発マシンで 2 つのノードクラスターをシミュレートします。

    マスターの起動

    $ domain.sh --host-config=host-master.xml

    スレーブの起動

    $ domain.sh --host-config=host-slave.xml

  6. これを試すには、ブラウザーを開き、http://localhost:8080/auth に移動します。

3.4. クロスサイトレプリケーションモードの使用

注記

クロスサイトレプリケーションモードは Technology Preview であり、完全にはサポートされていません。

クロスサイトレプリケーションモードを使用して、複数のデータセンターにまたがるクラスターで Red Hat Single Sign-On を実行します。通常、地理的に異なる地域にあるデータセンターサイトを使用します。このモードを使用すると、各データセンターには Red Hat Single Sign-On サーバーの独自のクラスターがあります。

このドキュメントでは、簡単なクロスサイトレプリケーションのユースケースを説明するために、以下のアーキテクチャー図の例を参照します。

アーキテクチャーダイアグラムの例

cross dc architecture

3.4.1. 前提条件

これは高度なトピックであるため、最初に以下を読むことをお勧めします。これは重要な背景知識を提供します。

  • クロスサイトのレプリケーションを設定する場合、Red Hat Single Sign-On でのクラスタリング では、より独立した Red Hat Single Sign-On クラスターを使用するため、クラスターの仕組み、負荷分散、共有データベース、マルチキャストなどの基本的な概念や要件を理解する必要があります。
  • Red Hat Data Grid Cross-Site Replication Red Hat Single Sign-On は、データセンター間のデータのレプリケーションに Red Hat Data Grid (RHDG) を使用します。

3.4.2. 技術的な詳細

このセクションでは、Red Hat Single Sign-On クロスサイトレプリケーションを実現する方法の概念と詳細について説明します。

データ

Red Hat Single Sign-On はステートフルなアプリケーションです。データソースとして以下を使用します。

  • データベースは、ユーザー情報などの永続データの永続化に使用されます。
  • Infinispan キャッシュは、データベースから永続データをキャッシュするために使用されます。また、ユーザーセッションなど、短命で頻繁に変更されるメタデータを保存するためにも使用されます。通常、Infinispan はデータベースよりもはるかに高速ですが、Infinispan を使用して保存されたデータは永続的ではなく、クラスターの再起動後も持続することは期待されていません。

このアーキテクチャー例では、site1site2 という 2 つのデータセンターがあります。クロスサイトレプリケーションの場合は、データのソースの両方が確実に機能し、site1 の Red Hat Single Sign-On サーバーが site2 の Red Hat Single Sign-On サーバーに保存されているデータを読み込めるようにする必要があります。

環境に基づいて、以下を希望するかどうかを決定するオプションがあります。

  • 信頼性: 通常 Active/Active モードで使用されます。site1 に書き込まれたデータは、すぐに site2 に表示される必要があります。
  • パフォーマンス - 通常は Active/Passive モードで使用されます。site1 に書き込まれたデータは、site2 上ですぐに表示される必要はありません。データが site2 に全く表示されない場合があります。

詳細は、「モード」 を参照してください。

3.4.3. 要求処理

エンドユーザーのブラウザーは HTTP リクエストを フロントエンドロードバランサー に送信します。このロードバランサーは通常、mod_cluster、NGINX、HA Proxy、またはその他の種類のソフトウェアやハードウェアロードバランサーを持つ HTTPD または WildFly です。

ロードバランサーは、受信する HTTP リクエストを、基礎となる Red Hat Single Sign-On インスタンスに転送します。これは、複数のデータセンターに分散できます。ロードバランサーは通常、スティッキーセッション のサポートを提供します。つまり、ロードバランサーはすべての HTTP リクエストを同じユーザーから同じデータセンターの同じ Red Hat Single Sign-On インスタンスに常に転送できます。

クライアントアプリケーションからロードバランサーに送信される HTTP 要求は バックチャネル要求 と呼ばれます。これらはエンドユーザーのブラウザーによって認識されないため、ユーザーとロードバランサー間でスティッキーセッションの一部にすることはできません。バックチャネル要求の場合、ロードバランサーは HTTP リクエストを、任意のデータセンター内の任意の Red Hat Single Sign-On インスタンスに転送することができます。一部の OpenID Connect および SAML フローではユーザーとアプリケーションの両方からの複数の HTTP 要求が必要となるため、これは困難です。スティッキーセッションを確実に依存して、関連するすべての要求を同じデータセンター内の同じ Red Hat Single Sign-On インスタンスに送信するように可能性があるため、代わりにデータセンター間でいくつかのデータを複製する必要があるため、データは特定のフロー中に後続の HTTP リクエストによって表示されます。

3.4.4. モード

要件に応じて、クロスサイトレプリケーションには、基本的な操作モードが 2 つあります。

  • Active/Passive: ここでは、ユーザーとクライアントアプリケーションは、1 つのデータセンターだけで Red Hat Single Sign-On ノードに要求を送信します。2 つ目のデータセンターは、データを保存する backup として使用されます。メインデータセンターで障害が発生した場合には、通常、2 番目のデータセンターからデータを復元することができます。
  • Active/Active: 以下に、ユーザーとクライアントアプリケーションは、両方のデータセンターの Red Hat Single Sign-On ノードに要求を送信します。つまり、両方のサイトでデータが即座に表示され、Red Hat Single Sign-On サーバーから即座に利用可能な状態にする必要があります。これは、Red Hat Single Sign-On サーバーが site1 に一部のデータを書き込む場合に特に当てはまり、site1 への書き込みが終了した直後に site2 でそのデータを Red Hat Single Sign-On サーバーがすぐに読み取れるようにする必要があります。

パフォーマンスには、active/passive モードが適しています。いずれかのモードにキャッシュを設定する方法の詳細は、「SYNC または ASYNC バックアップ」 を参照してください。

3.4.5. データベース

Red Hat Single Sign-On はリレーショナルデータベース管理システム (RDBMS) を使用して、レルム、クライアント、ユーザーなどのメタデータを永続化します。詳細は、『サーバーインストールガイド』の こちらの を参照してください。クロスサイトレプリケーション設定では、データセンターはいずれも同じデータベースと対話するか、またはすべてのデータセンターに独自のデータベースノードがあり、両方のデータベースノードがデータセンター全体で同期的に複製されることを前提とします。いずれの場合も、site1 の Red Hat Single Sign-On サーバーが一部のデータを永続化し、トランザクションをコミットすると、これらのデータは site2 の後続の DB トランザクションによって即座に表示されます。

DB 設定の詳細は、Red Hat Single Sign-On の範囲外になりますが、MariaDB のような多くの RDBMS ベンダーは複製されたデータベースと同期レプリケーションを提供します。以下のベンダーを使用して Red Hat Single Sign On をテストします。

  • Oracle Database 19c RAC
  • Galera 3.12 cluster for MariaDB server version 10.1.19-MariaDB

3.4.6. Infinispan キャッシュ

このセクションは、Infinispan キャッシュに関するハイレベルな説明から始まります。キャッシュ設定の詳細は、次のとおりです。

認証セッション

Red Hat Single Sign-On では、認証セッションの概念があります。特定のユーザーの認証中にデータを保存するために使用される authenticationSessions という別の Infinispan キャッシュがあります。通常、このキャッシュからの要求は、アプリケーションではなくブラウザーと Red Hat Single Sign-On サーバーのみが必要になります。ここでは、スティッキーセッションに依存し、authenticationSessions キャッシュコンテンツを Active/Active モードであってもデータセンター全体に複製する必要はありません。

永続データのキャッシュおよび無効化

Red Hat Single Sign-On は Infinispan を使用して永続データをキャッシュし、データベースに対する不要な要求を回避します。キャッシュによりパフォーマンスが向上しますが、さらなる課題が追加されます。一部の Red Hat Single Sign-On サーバーがデータを更新する場合は、すべてのデータセンターにある他のすべての Red Hat Single Sign-On サーバーを認識するため、キャッシュから特定のデータを無効化する必要があります。Red Hat Single Sign-On は、レルムユーザー、および 認証 と呼ばれるローカルの Infinispan キャッシュを使用して永続データをキャッシュします。

すべてのデータセンターにレプリケートされる別のキャッシュ work を使用します。作業キャッシュ自体は実際のデータをキャッシュしません。これは、クラスターノードとデータセンター間の無効化メッセージ送信にのみ使用されます。つまり、ユーザー john などのデータを更新すると、Red Hat Single Sign-On ノードは、同じデータセンターおよび他のすべてのデータセンターの他のすべてのクラスターノードに無効化メッセージを送信します。無効化通知を受信した後、すべてのノードはローカルキャッシュからの適切なデータを無効化します。

ユーザーセッション

sessionsclientSessionsofflineSessions、および offlineClientSessions と呼ばれる Infinispan キャッシュがあります。これらはすべてデータセンター全体に複製する必要があります。これらのキャッシュは、ユーザーのブラウザーセッションの長さに有効なユーザーセッションに関するデータを保存するために使用されます。キャッシュは、エンドユーザーおよびアプリケーションからの HTTP リクエストを処理する必要があります。上記のように、スティッキーセッションは、このインスタンスでは確実に使用しないようにしてくださいが、後続の HTTP リクエストが最新のデータを認識できるようにする必要があります。このため、データは通常データセンター全体で複製されます。

ブルートフォース保護

最後に loginFailures キャッシュを使用して、ユーザー john が不正なパスワードを入力した回数など、失敗したログインに関するデータを追跡します。詳細は、を参照して ください。このキャッシュをデータセンター全体で複製する必要があるかどうかは、管理者次第になります。ログインの失敗を正確にカウントするには、レプリケーションが必要です。一方、このデータを複製しないことで、一部のパフォーマンスを節約できます。したがって、ログインの失敗の正確なカウントよりもパフォーマンスの方が重要な場合は、レプリケーションを回避できます。

キャッシュの設定方法の詳細は、「RHDG キャッシュ設定のチューニング」 を参照してください。

3.4.7. 通信の詳細

Red Hat Single Sign-On は、Infinispan キャッシュの複数の個別のクラスターを使用します。Red Hat Single Sign-On ノードはすべて、同じデータセンターにある他の Red Hat Single Sign-On ノードを持つクラスターにありますが、異なるデータセンターにある Red Hat Single Sign-On ノードとは記載されていません。Red Hat Single Sign-On ノードは、異なるデータセンターからの Red Hat Single Sign-On ノードと直接通信しません。Red Hat Single Sign-On ノードは、データセンター間の通信に外部 JDG(実際には RHDG サーバー)を使用します。これは Infinispan HotRod プロトコル を使用して行われます。

データがリモートキャッシュに保存されるように、Red Hat Single Sign-On 側で Infinispan キャッシュを remoteStore で設定する必要があります。JDG サーバーには個別の Infinispan クラスターがあるため、site1 の JDG1 に保存されるデータは site2 の JDG2 にレプリケートされます。

受信側の RHDG サーバーは、Hot Rod プロトコルの機能であるクライアントリスナーを介して、クラスター内の Red Hat Single Sign-On サーバーに通知します。site2 の Red Hat Single Sign-On ノードは、Infinispan キャッシュを更新し、特定のユーザーセッションが site2 の Red Hat Single Sign-On ノードにも表示されます。

詳細は、アーキテクチャーダイアグラムの例 を参照してください。

3.4.8. クロスサイトレプリケーションの設定

RHDG 8.x で以下の手順を使用して、クロスサイトレプリケーションの基本設定を行います。

注記

RHDG のバージョンに関する手順は、以下の手順と若干異なる可能性があります。RHDG 8.1 に適用されます。説明通りに機能しないステップについては、RHDG のドキュメントを確認してください。

RHDG 8.x の例では、site1site2 の 2 つのデータセンターを使用します。各データセンターは、1 つの RHDG サーバーと 2 つの Red Hat Single Sign-On サーバーで構成されます。最終的には、合計 2 つの RHDG サーバーと 4 つの Red Hat Single Sign-On サーバーになります。

  • Site1 は、RHDG サーバー、server1、および 2 つの Red Hat Single Sign-On サーバー、node11node12 で構成されます。
  • Site2 は、RHDG サーバー、server2、および 2 つの Red Hat Single Sign-On サーバー、node21node22 で構成されます。
  • RHDG サーバー server1 および server2 は、RHDG documentation の説明と同様の方法で、RELAY2 プロトコルおよび backup ベースの RHDG キャッシュを介して相互に接続されます。
  • Red Hat Single Sign-On サーバー node11node12 は、相互にクラスターを形成しますが、site2 のサーバーと直接通信しません。これらは、Hot Rod プロトコル (リモートキャッシュ) を使用して Infinispan サーバーの server1 と通信します。詳細は、「通信の詳細」 を参照してください。
  • node21 および node22 にも同じ情報が適用されます。これらのクラスターは相互にクラスター化し、Hot Rod プロトコルを使用して server2 サーバーのみと通信します。

設定例では、4 つの Red Hat Single Sign-On サーバーが同じデータベースと対話することを想定しています。実稼働環境では、「データベース」 の説明に従って、データセンター全体に同期的に複製された別のデータベースを使用することが推奨されます。

3.4.8.1. RHDG サーバーの設定

クロスサイトレプリケーションの場合、Red Hat Single Sign-On データをバックアップすることができるリモート RHDG クラスターを作成して開始します。

前提条件

  • RHDG Server 8.x をダウンロードしてインストールします。
注記

RHDG Server 8.x には Java 11 が必要です。

手順

  1. RHDG からのクライアント接続を認証するユーザーを作成します。以下に例を示します。

    $ bin/cli.sh user create myuser -p "qwer1234!"
    注記

    Red Hat Single Sign-On でリモートキャッシュを作成する際に、Hot Rod クライアント設定でこれらの認証情報を指定します。

  2. 以下のように、SSL キーストアおよびトラストストアを作成し、RHDG と Red Hat Single Sign-On 間の接続を保護します。

    1. キーストアを作成して、RHDG クラスターに SSL アイデンティティーを提供します。

      keytool -genkey -alias server -keyalg RSA -keystore server.jks -keysize 2048
    2. キーストアから SSL 証明書をエクスポートします。

      keytool -exportcert -keystore server.jks -alias server -file server.crt
    3. Red Hat Single Sign-On が使用可能なトラストストアに SSL 証明書をインポートして、RHDG の SSL アイデンティティーを確認します。

      keytool -importcert -keystore truststore.jks -alias server -file server.crt
    4. server.crt を削除します。

      rm server.crt

3.4.8.2. RHDG クラスターの設定

データセンター全体で Red Hat Single Sign-On データを複製するように RHDG クラスターを設定します。

前提条件

  • RHDG サーバーをインストールして設定します。

手順

  1. infinispan.xml を開いて編集します。

    デフォルトでは、RHDG Server は、クラスタートランスポートやセキュリティーメカニズムなどの静的設定に server/conf/infinispan.xml を使用します。

  2. TCPPING をクラスター検出プロトコルとして使用するスタックを作成します。

    <stack name="global-cluster" extends="tcp">
        <!-- Remove MPING protocol from the stack and add TCPPING -->
        <TCPPING initial_hosts="server1[7800],server2[7800]" 1
                 stack.combine="REPLACE" stack.position="MPING"/>
    </stack>
    1
    server1 および server2 のホスト名を一覧表示します。
  3. クロスサイトレプリケーションを実行するように RHDG クラスタートランスポートを設定します。

    1. RELAY2 プロトコルを JGroups スタックに追加します。

      <jgroups>
         <stack name="xsite" extends="udp"> 1
            <relay.RELAY2 site="site1" 2
                          max_site_masters="1000"/> 3
            <remote-sites default-stack="global-cluster"> 4
               <remote-site name="site1"/>
               <remote-site name="site2"/>
            </remote-sites>
         </stack>
      </jgroups>
      1
      デフォルトの UDP クラスタートランスポート を拡張する xsite という名前のスタックを作成します。
      2
      RELAY2 プロトコルを追加し、設定しているクラスターに site1 という名前を付けます。サイト名は、各 RHDG クラスターに固有のものである必要があります。
      3
      クラスターのリレーノードの数として 1000 を設定します。RHDG クラスターのノードの最大数と同じか、それより大きい値を設定する必要があります。
      4
      RHDG データを使用してキャッシュをバックアップするすべての RHDG クラスターに名前を付け、クラスター間転送にデフォルトの TCP スタックを使用します。
    2. スタックを使用するように RHDG クラスタートランスポートを設定します。

      <cache-container name="default" statistics="true">
            <transport cluster="${infinispan.cluster.name:cluster}"
                       stack="xsite"/> 1
      </cache-container>
      1
      クラスターに xsite スタックを使用します。
  4. サーバーセキュリティーレルムでキーストアを SSL アイデンティティーとして設定します。

    <server-identities>
      <ssl>
        <keystore path="server.jks" 1
                  relative-to="infinispan.server.config.path"
                  keystore-password="password" 2
                  alias="server" /> 3
      </ssl>
    </server-identities>
    1
    SSL アイデンティティーが含まれるキーストアのパスを指定します。
    2
    キーストアにアクセスするためのパスワードを指定します。
    3
    キーストア内の証明書のエイリアスに名前を付けます。
  5. Hot Rod エンドポイントの認証メカニズムを設定します。

    <endpoints socket-binding="default">
       <hotrod-connector name="hotrod">
          <authentication>
             <sasl mechanisms="SCRAM-SHA-512" 1
                   server-name="infinispan" /> 2
          </authentication>
       </hotrod-connector>
       <rest-connector name="rest"/>
    </endpoints>
    1
    Hot Rod エンドポイントの SASL 認証メカニズムを設定します。SCRAM-SHA-512 は、Hot Rod のデフォルトの SASL メカニズムです。ただし、GSSAPI など、環境に適したものなら何でも使用できます。
    2
    RHDG サーバーがクライアントに提示する名前を定義します。Red Hat Single Sign-On を設定する際に、この名前を Hot Rod クライアント設定で指定します。
  6. キャッシュテンプレートを作成します。

    注記

    RHDG クラスターの各ノードの infinispan.xml にキャッシュテンプレートを追加します。

    <cache-container ... >
      <replicated-cache-configuration name="sessions-cfg" 1
                                      mode="SYNC"> 2
        <locking acquire-timeout="0" /> 3
        <backups>
          <backup site="site2" strategy="SYNC" /> 4
        </backups>
      </replicated-cache-configuration>
    </cache-container>
    1
    sessions-cfg という名前のキャッシュテンプレートを作成します。
    2
    クラスター全体でデータを同期的に複製するキャッシュを定義します。
    3
    ロック取得のタイムアウトを無効にします。
    4
    設定している RHDG クラスターのバックアップサイトに名前を付けます。
  7. RHDG server1 を起動します。

    ./server.sh -c infinispan.xml -b PUBLIC_IP_ADDRESS -k PUBLIC_IP_ADDRESS -Djgroups.mcast_addr=228.6.7.10
  8. RHDG server2 を起動します。

    ./server.sh -c infinispan.xml -b PUBLIC_IP_ADDRESS -k PUBLIC_IP_ADDRESS -Djgroups.mcast_addr=228.6.7.11
  9. RHDG サーバーログをチェックして、クラスターがクロスサイトビューを形成していることを確認します。

    INFO  [org.infinispan.XSITE] (jgroups-5,${server.hostname}) ISPN000439: Received new x-site view: [site1]
    INFO  [org.infinispan.XSITE] (jgroups-7,${server.hostname}) ISPN000439: Received new x-site view: [site1, site2]

3.4.8.3. Infinispan キャッシュの作成

Red Hat Single Sign-On が必要とする Infinispan キャッシュを作成します。

キャッシュを infinispan.xml に追加するのではなく、ランタイム時に RHDG クラスターでキャッシュを作成することを推奨します。このストラテジーにより、キャッシュがクラスター全体で自動的に同期され、永続的に保存されます。

以下の手順では、RHDG コマンドラインインターフェース(CLI)を使用して、1 つのバッチコマンドで必要なすべてのキャッシュを作成します。

前提条件

  • RHDG クラスターを設定します。

手順

  1. キャッシュが含まれるバッチファイルを作成します。以下に例を示します。

    cat > /tmp/caches.batch<<EOF
    echo "creating caches..."
    create cache work --template=sessions-cfg
    create cache sessions --template=sessions-cfg
    create cache clientSessions --template=sessions-cfg
    create cache offlineSessions --template=sessions-cfg
    create cache offlineClientSessions --template=sessions-cfg
    create cache actionTokens --template=sessions-cfg
    create cache loginFailures --template=sessions-cfg
    echo "verifying caches"
    ls caches
    EOF
  2. CLI でキャッシュを作成します。

    $ bin/cli.sh -c https://server1:11222 --trustall -f /tmp/caches.batch
    注記

    --trustall 引数の代わりに、-t 引数とトラストストアパスワードを -s 引数と共に指定できます。

  3. 他のサイトでキャッシュを作成します。

3.4.8.4. Red Hat Single Sign-On でのリモートキャッシュストアの設定

リモート RHDG クラスターを設定したら、Red Hat Single Sign-On で Infinispan サブシステムを設定して、リモートストアでデータをこれらのクラスターに外部化します。

前提条件

  • クロスサイト設定用のリモート RHDG クラスターを設定している。
  • RHDG Server アイデンティティーを持つ SSL 証明書が含まれるトラストストアを作成している。

手順

  1. トラストストアを Red Hat Single Sign-On デプロイメントに追加します。
  2. RHDG クラスターを参照するソケットバインディングを作成します。

    <outbound-socket-binding name="remote-cache"> 1
      <remote-destination host="${remote.cache.host:server_hostname}" 2
                          port="${remote.cache.port:11222}"/> 3
    </outbound-socket-binding>
    1
    ソケットバインディングに remote-cache という名前を付けます。
    2
    RHDG クラスターのホスト名を 1 つ以上指定します。
    3
    Hot Rod エンドポイントがリッスンする 11222 のポートを定義します。
  3. org.keycloak.keycloak-model-infinispan モジュールを Infinispan サブシステムの keycloak キャッシュコンテナーに追加します。

    <subsystem xmlns="urn:jboss:domain:infinispan:12.0">
        <cache-container name="keycloak"
                         modules="org.keycloak.keycloak-model-infinispan"/>
  4. Infinispan サブシステムの work キャッシュを更新して、以下の設定が含まれるようにします。

    <replicated-cache name="work"> 1
        <remote-store cache="work" 2
                      remote-servers="remote-cache" 3
                      passivation="false"
                      fetch-state="false"
                      purge="false"
                      preload="false"
                      shared="true">
            <property name="rawValues">true</property>
            <property name="marshaller">org.keycloak.cluster.infinispan.KeycloakHotRodMarshallerFactory</property>
            <property name="infinispan.client.hotrod.auth_username">myuser</property>
            <property name="infinispan.client.hotrod.auth_password">qwer1234!</property>
            <property name="infinispan.client.hotrod.auth_realm">default</property>
            <property name="infinispan.client.hotrod.auth_server_name">infinispan</property>
            <property name="infinispan.client.hotrod.sasl_mechanism">SCRAM-SHA-512</property>
            <property name="infinispan.client.hotrod.trust_store_file_name">/path/to/truststore.jks</property>
            <property name="infinispan.client.hotrod.trust_store_type">JKS</property>
            <property name="infinispan.client.hotrod.trust_store_password">password</property>
        </remote-store>
    </replicated-cache>
    1
    RHDG 設定のキャッシュに名前を付けます。
    2
    リモート RHDG クラスター上の対応するキャッシュに名前を付けます。
    3
    remote-cache ソケットバインディングを指定します。

    上記のキャッシュ設定には、RHDG キャッシュに推奨される設定が含まれています。Hot Rod クライアント設定プロパティーは、RHDG ユーザー認証情報、SSL キーストア、およびトラストストアの詳細を指定します。

    各プロパティーの説明については、RHDG documentation を参照してください。

  5. 以下のキャッシュごとに、分散キャッシュを Infinispan サブシステムに追加します。

    • セッション
    • clientSessions
    • offlineSessions
    • offlineClientSessions
    • actionTokens
    • loginFailures

      たとえば、以下の設定で sessions という名前のキャッシュを追加します。

      <distributed-cache name="sessions" 1
                         owners="1"> 2
          <remote-store cache="sessions" 3
                        remote-servers="remote-cache" 4
                        passivation="false"
                        fetch-state="false"
                        purge="false"
                        preload="false"
                        shared="true">
              <property name="rawValues">true</property>
              <property name="marshaller">org.keycloak.cluster.infinispan.KeycloakHotRodMarshallerFactory</property>
              <property name="infinispan.client.hotrod.auth_username">myuser</property>
              <property name="infinispan.client.hotrod.auth_password">qwer1234!</property>
              <property name="infinispan.client.hotrod.auth_realm">default</property>
              <property name="infinispan.client.hotrod.auth_server_name">infinispan</property>
              <property name="infinispan.client.hotrod.sasl_mechanism">SCRAM-SHA-512</property>
              <property name="infinispan.client.hotrod.trust_store_file_name">/path/to/truststore.jks</property>
              <property name="infinispan.client.hotrod.trust_store_type">JKS</property>
              <property name="infinispan.client.hotrod.trust_store_password">password</property>
          </remote-store>
      </distributed-cache>
      1
      RHDG 設定のキャッシュに名前を付けます。
      2
      RHDG クラスター全体で各キャッシュエントリーの 1 つのレプリカを設定します。
      3
      リモート RHDG クラスター上の対応するキャッシュに名前を付けます。
      4
      remote-cache ソケットバインディングを指定します。
  6. NODE11 を、後で NODE12NODE21、および NODE22 と呼ばれる他の 3 つのディレクトリーにコピーします。
  7. NODE11 を起動します。

    cd NODE11/bin
    ./standalone.sh -c standalone-ha.xml -Djboss.node.name=node11 -Djboss.site.name=site1 \
      -Djboss.default.multicast.address=234.56.78.1 -Dremote.cache.host=server1 \
      -Djava.net.preferIPv4Stack=true -b PUBLIC_IP_ADDRESS

    ログで以下の警告メッセージに気づいた場合は、無視しても問題ありません。

    WARN  [org.infinispan.CONFIG] (MSC service thread 1-5) ISPN000292: Unrecognized attribute 'infinispan.client.hotrod.auth_password'. Please check your configuration. Ignoring!
    WARN  [org.infinispan.CONFIG] (MSC service thread 1-5) ISPN000292: Unrecognized attribute 'infinispan.client.hotrod.auth_username'. Please check your configuration. Ignoring!
  8. NODE12 を起動します。

    cd NODE12/bin
    ./standalone.sh -c standalone-ha.xml -Djboss.node.name=node12 -Djboss.site.name=site1 \
      -Djboss.default.multicast.address=234.56.78.1 -Dremote.cache.host=server1 \
      -Djava.net.preferIPv4Stack=true -b PUBLIC_IP_ADDRESS

    クラスターノードは接続されている必要があります。以下のような内容は、NODE11 と NODE12 の両方のログにあるはずです。

    Received new cluster view for channel keycloak: [node11|1] (2) [node11, node12]
    注記

    ログのチャネル名は異なる場合があります。

  9. NODE21 を起動します。

    cd NODE21/bin
    ./standalone.sh -c standalone-ha.xml -Djboss.node.name=node21 -Djboss.site.name=site2 \
      -Djboss.default.multicast.address=234.56.78.2 -Dremote.cache.host=server2 \
      -Djava.net.preferIPv4Stack=true -b PUBLIC_IP_ADDRESS

    NODE11 および NODE12 のクラスターに接続するのではなく、別のクラスターに接続する必要があります。

    Received new cluster view for channel keycloak: [node21|0] (1) [node21]
  10. NODE22 を起動します。

    cd NODE22/bin
    ./standalone.sh -c standalone-ha.xml -Djboss.node.name=node22 -Djboss.site.name=site2 \
      -Djboss.default.multicast.address=234.56.78.2 -Dremote.cache.host=server2 \
      -Djava.net.preferIPv4Stack=true -b PUBLIC_IP_ADDRESS

    NODE21 のクラスターにする必要があります。

    Received new cluster view for channel keycloak: [node21|1] (2) [node21, node22]
    注記

    ログのチャネル名は異なる場合があります。

  11. テスト:

    1. http://node11:8080/auth/ にアクセスし、初期管理ユーザーを作成します。
    2. http://node11:8080/auth/admin にアクセスし、管理者として管理コンソールにログインします。
    3. 2 つ目のブラウザーを開き、http://node12:8080/auth/adminhttp://node21:8080/auth/admin、または http://node22:8080/auth/admin のノードのいずれかに移動します。ログイン後、4 台のすべてのサーバーで、特定のユーザー、クライアント、またはレルムの Sessions タブで上同じセッションを確認できるはずです。
    4. ユーザーまたはレルムの変更など、Red Hat Single Sign-On の管理コンソールに変更を加えた後、その変更は 4 つのノードのいずれかですぐに表示されるはずです。キャッシュはどこでも適切に無効化する必要があります。
    5. 必要に応じて server.logs を確認します。ログインまたはログアウトの後に、以下のようなメッセージがすべてのノードの NODEXY/standalone/log/server.log に追加されるはずです。

      2017-08-25 17:35:17,737 DEBUG [org.keycloak.models.sessions.infinispan.remotestore.RemoteCacheSessionListener] (Client-Listener-sessions-30012a77422542f5) Received event from remote store.
      Event 'CLIENT_CACHE_ENTRY_REMOVED', key '193489e7-e2bc-4069-afe8-f1dfa73084ea', skip 'false'

3.4.9. クロスサイトデプロイメントの管理

このセクションでは、クロスサイトレプリケーションに関するヒントおよびオプションについて説明します。

  • データセンター内で Red Hat Single Sign-On サーバーを実行する場合は、KeycloakDS データソースで参照されているデータベースがすでに実行されており、そのデータセンターで利用可能である必要があります。また、Infinispan キャッシュの remote-store 要素から参照される outbound-socket-binding によって参照される RHDG サーバーがすでに実行されている必要があります。それ以外の場合は、Red Hat Single Sign-On サーバーは起動に失敗します。
  • データベースのフェイルオーバーをサポートする必要がある場合、すべてのデータセンターにはデータベースノードが多くなり、信頼性が向上します。データベース側でこれを設定する方法と、Keycloak で KeycloakDS データソースを設定する方法に関する詳細は、データベースおよび JDBC ドライバーのドキュメントを参照してください。
  • すべてのデータセンターで、クラスター内でより多くの RHDG サーバーを実行できます。これは、一部のフェイルオーバーとフォールトトレランスを強化する場合に役立ちます。RHDG サーバーと Red Hat Single Sign-On サーバー間の通信に使用される Hot Rod プロトコルには、RHDG サーバーが RHDG クラスターで変更に関する Red Hat Single Sign-On サーバーに自動的に新しいトポロジーを送信する機能があるため、Red Hat Single Sign-On のリモートストアは、接続可能な RHDG サーバーを認識します。詳細は、RHDG および WildFly のドキュメントを参照してください。
  • master の RHDG サーバーが 任意の サイトの Red Hat Single Sign-On サーバーを起動する前に、すべてのサイトで稼働していることを強く推奨します。この例では、すべての Red Hat Single Sign-On サーバーの前に、server1server2 の両方を最初に起動しました。Red Hat Single Sign-On サーバーを引き続き実行する必要があり、バックアップサイトがオフラインである場合は、「サイトのオフラインおよびオンライン化」 の説明にあるように、サイトの RHDG サーバーでバックアップサイトを手動でオフラインに切り替えることが推奨されます。利用できないサイトを手動でオフラインに切り替えないと、最初の起動に失敗するか、設定された失敗した操作の数が原因でバックアップサイトが自動的にオフラインになるまで、起動中にいくつかの例外が発生する可能性があります。

3.4.10. サイトのオフラインおよびオンライン化

たとえば、以下のシナリオを想定します。

  1. site2 は、site1 パースペクティブから完全にオフラインになっています。つまり、site2 のすべての RHDG サーバーがオフになっているか、または site1site2 との間のネットワークが破損していることを意味します。
  2. サイト site1 で、Red Hat Single Sign-On サーバーおよび RHDG サーバー server1 を実行します。
  3. あるユーザーが、site1 の Red Hat Single Sign-On サーバーにログインします。
  4. site1 の Red Hat Single Sign-On サーバーは、server1 サーバーのリモートキャッシュにセッションの書き込みを試みます。これは、データを site2server2 サーバーにバックアップすることになります。詳細は、「通信の詳細」 を参照してください。
  5. サーバー server2 はオフラインであるか、または server1 から到達できません。そのため、server1 から server2 へのバックアップは失敗します。
  6. デフォルトの FAIL バックアップ失敗ポリシーが設定されているため、例外が server1 ログに出力されると、その失敗が server1 サーバーから Red Hat Single Sign-On サーバーにも伝播されます。バックアップポリシーの詳細は、バックアップ障害ポリシー を参照してください。
  7. Red Hat Single Sign-On 側でもエラーが発生し、ユーザーはログインを完了できない可能性があります。

ご使用の環境によっては、サイト間のネットワークが利用不可であるか、一時的に破損 (スプリットブレイン) している可能性があります。このような場合は、site1 の RHDG サーバーは、site2 の RHDG サーバーが利用不可であることを認識しているため、これらのサーバーは server2 サイトのサーバーに到達しようとしなくなり、バックアップの失敗が発生しません。これは、Take site offline と呼ばれます。

サイトをオフラインにする

サイトをオフラインにする方法は 2 つあります。

管理者が手動で - 管理者は jconsole またはその他のツールを使用し、JMX 操作を実行して特定のサイトを手動でオフラインにすることができます。これは特に、停止が予定されている場合に役に立ちます。jconsole または CLI を使用すると、server1 サーバーに接続し、site2 をオフラインにすることができます。詳細は、RHDG のドキュメント を参照してください

警告

この手順は、通常、「SYNC または ASYNC バックアップ」 に記載されているすべての Red Hat Single Sign-On キャッシュに対して実行する必要があります。

自動 - バックアップの失敗が一定になると、通常、site2 は自動的にオフラインになります。これは、キャッシュ設定内の take-offline 要素の設定が原因で行われます。

<take-offline min-wait="60000" after-failures="3" />

この例は、その後に少なくとも 3 回失敗したバックアップがあり、60 秒以内に成功したバックアップがない場合は、特定の単一キャッシュに対してサイトが自動的にオフラインになることを示しています。

自動的にサイトをオフラインにすることは、サイト間の破損したネットワークが予定外の場合に特に役立ちます。欠点は、ネットワークの停止が検出されるまで、バックアップが何度か失敗することです。これは、アプリケーション側でも障害があることを意味する場合があります。たとえば、一部のユーザーのログインに失敗したり、ログインのタイムアウトが大きくなったりします。特に、値 FAILfailure-policy が使用される場合。

警告

サイトがオフラインであるかどうかの追跡は、キャッシュごとに個別に追跡されます。

サイトをオンラインにする

ネットワークが復旧し、site1site2 が相互に通信できるようになったら、サイトをオンラインにする必要がある場合があります。これは、サイトをオフラインにするのと同様に、JMX または CLI を使用して手動で行う必要があります。ここでも、すべてのキャッシュを確認してオンラインにする必要がある場合もあります。

サイトがオンラインになると、通常は以下を実行することができます。

3.4.11. 状態遷移

状態遷移は、必要な手動による手順です。RHDG サーバーはこれを自動的に行いません。たとえば、スプリットブレインの間に、どちらのサイトが優先されるのか、そして状態遷移は両方のサイト間で双方向に、または site2 から site1 ではなく、site1 から site2 のみの一方向にのみ行う必要があるのかを決定できるのは、管理者だけになります。

双方向状態遷移により、site1 のスプリットブレイン に作成されたエンティティーが site2 に転送されます。これらはまだ site2 に存在しないため、これは問題ではありません。同様に、site2 のスプリットブレイン に作成されたエンティティーは site1 に転送されます。問題となる可能性のある部分は、サイト上でスプリットブレインの に存在し、両方のサイトでスプリットブレイン中に更新されたエンティティーです。これが発生すると、いずれかのサイトが 優先され、2 番目のサイトでスプリットブレイン中に実行された更新が上書きされます。

残念ながら、これに対する普遍的な解決策はありません。スプリットブレインとネットワークの停止は単なる状態であり、サイト間で 100%一貫したデータを使用して 100%正しく処理することは通常不可能です。Red Hat Single Sign-On の場合、通常は重要な問題ではありません。最悪のケースでは、ユーザーはクライアントに再度ログインし直す必要があります。または、ブルートフォース攻撃からの保護のために、不適切な loginFailures の数を追跡する必要があります。スプリットブレインへの対処方法についてのヒントは、RHDG/JGroups のドキュメントを参照してください。

状態遷移は、JMX 経由で RHDG サーバー側で行うこともできます。操作名は pushState です。ステータスの監視、プッシュ状態のキャンセルなど、他の操作はほとんどありません。状態遷移に関する詳細は、RHDG ドキュメント を参照してください

3.4.12. キャッシュのクリア

スプリットブレインの後、Red Hat Single Sign-On の管理コンソールでキャッシュを手動で安全にクリアできます。これは、site1 のデータベースに一部のデータが変更された可能性があり、イベントが原因でキャッシュが無効になり、スプリットブレイン中に site2 に転送されなかったためです。したがって、site2 の Red Hat Single Sign-On ノードには、キャッシュに古いデータが残っている可能性があります。

キャッシュを削除するには、「サーバーキャッシュ のクリア」を参照して ください。

ネットワークが復旧したら、任意のランダムサイトの 1 つの Red Hat シングルサインオンノードでキャッシュをクリアするだけで十分です。キャッシュの無効化イベントは、すべてのサイトの他のすべての Red Hat Single Sign-On ノードに送信されます。ただし、すべてのキャッシュ (レルム、ユーザー、キー) に対して実行する必要があります。詳細は、「 サーバーキャッシュ の削除」を参照してください。

3.4.13. RHDG キャッシュ設定のチューニング

このセクションには、JDG キャッシュを設定するためのヒントおよびオプションが含まれています。

バックアップ障害ポリシー

デフォルトでは、RHDG clustered.xml ファイルの Infinispan キャッシュ設定におけるバックアップの failure-policy の設定は、FAIL として設定されます。必要に応じて WARN または IGNORE に変更できます。

FAILWARN の違いは、FAIL が使用され、RHDG サーバーが別のサイトにデータのバックアップを試み、バックアップが失敗すると、障害が呼び出し元 (Red Hat Single Sign-On サーバー) に伝播される点です。2 番目のサイトが一時的にアクセスできないか、同じエンティティーを更新しようとしている同時トランザクションが存在するため、バックアップが失敗する可能性があります。この場合、Red Hat Single Sign-On サーバーは、操作を数回再試行します。ただし、再試行に失敗すると、長いタイムアウト後にエラーが表示される可能性があります。

WARN を使用する場合、失敗したバックアップは RHDG サーバーから Red Hat Single Sign-On サーバーに伝播されません。ユーザーにはエラーが表示されず、失敗したバックアップは無視されます。タイムアウトは短くなります。バックアップのデフォルトのタイムアウトであるため、通常は 10 秒です。これは、backup 要素の属性 timeout で変更できます。再試行はありません。RHDG サーバーログに警告メッセージが表示されるだけです。

潜在的な問題は、場合によっては、サイト間のわずかなネットワーク停止があり、再試行 (FAILポリシーの使用) が役立つ可能性があるため、WARN (再試行なし) を使用すると、サイト全体でデータの不整合が発生することです。これは、両方のサイトで同時に同じエンティティーの更新を試みる場合にも発生する可能性があります。

これらの不整合は、どの程度の悪影響がありますか?通常は、ユーザーによる再認証が必要であることを意味するだけです。

WARN ポリシーを使用する場合は、actionTokens キャッシュによって提供される単一使用キャッシュと、その特定のキーが実際に単一の使用を処理するものの、「成功」が同じ鍵を 2 回書き込む可能性があります。たとえば、OAuth2 仕様では、コードを単一使用でなければならないことが 言及 されています。WARN ポリシーでは、厳密に保証されない可能性があり、両方のサイトで同時に書き込みしようとすると、同じコードが 2 回書き込まれる可能性があります。

ネットワークの停止またはスプリットブレインが長くなる場合、FAILWARN の両方で、「サイトのオフラインおよびオンライン化」 で説明しているように、一定時間後および失敗後に他のサイトがオフラインになります。デフォルトの 1 分タイムアウトでは、関係するすべてのキャッシュがオフラインになるまで 1 ~ 3 分かかります。その後、エンドユーザーの観点からすべての操作は問題なく機能します。「サイトのオフラインおよびオンライン化」 で説明しているように、サイトがオンラインに戻る場合に、手動でサイトを復元する必要があるだけです。

要約すると、サイト間で頻繁に長い停止が発生することが予想され、データの不整合や 100% 正確でない 1 回限りのキャッシュがあることには許容できても、エンドユーザーにエラーや長いタイムアウトを表示させたくない場合は、WARN に切り替えます。

WARNIGNORE の違いは、IGNORE 警告は RHDG ログに書き込まれないことです。詳細は Infinispan ドキュメントを参照してください。

ロック取得のタイムアウト

デフォルト設定は、取得タイムアウト 0 の NON_DURABLE_XA モードでトランザクションを使用します。これは、同じキーに対して進行中の別のトランザクションがある場合、トランザクションがフェイルファストになることを意味します。

これをデフォルトの 10 秒ではなく 0 に切り替える理由は、デッドロックの問題を回避するためです。Red Hat Single Sign-On では、同じエンティティー (通常はセッションエンティティーまたは loginFailure) が両方のサイトから同時に更新される場合があります。これにより、状況によってはデッドロックが発生し、トランザクションが 10 秒間ブロックされる可能性があります。詳細は、この JIRA レポート を参照してください。

タイムアウト 0 の場合、トランザクションは直ちに失敗し、値 FAIL が設定されたバックアップの failure-policyが設定されている場合は、Red Hat Single Sign-On から再試行されます。2 番目の同時トランザクションが終了している限り、通常、再試行は成功し、エンティティーは両方の同時トランザクションからの更新を適用します。

この設定の同時トランザクションに関する非常に優れた一貫性と結果が得られており、維持することが推奨されます。

唯一の (機能なし) は、RHDG サーバーログの例外です。これは、ロックがすぐに利用できない場合に毎回発生します。

3.4.14. SYNC または ASYNC バックアップ

backup 要素の重要な部分は strategy 属性です。SYNC または ASYNC のどちらであるかを決定する必要があります。クロスサイトレプリケーションが認識する可能性のあるキャッシュは 7 つあります。これらは、クロスサイトについて 3 つの異なるモードで設定することができます。

  1. SYNC バックアップ
  2. ASYNC バックアップ
  3. バックアップはまったくありません

SYNC バックアップが使用されると、バックアップは同期され、2 番目のサイトでバックアップが処理されると、バックアップは呼び出し元 (Red Hat Single Sign-On サーバー) 側で完了とみなされます。これは ASYNC よりもパフォーマンスが低下しますが、一方で、site2 のユーザーセッションのような特定のエンティティーの後続の読み取りは site1 からの更新を見るようになります。また、データの一貫性を確保する必要がある場合にも必要になります。ASYNC と同様に、他のサイトへのバックアップに失敗した場合は、呼び出し元に通知されません。

一部のキャッシュでは、バックアップをまったく行わず、RHDG サーバーへのデータの書き込みを完全にスキップすることも可能です。これを設定するには、Red Hat Single Sign-On 側の特定のキャッシュ (KEYCLOAK_HOME/standalone/configuration/standalone-ha.xml ファイル) に remote-store 要素を使用しないでください。そうすると、RHDG サーバー側でも特定の replicated-cache 要素が必要なくなります。

デフォルトでは、すべての 7 つのキャッシュは SYNC バックアップで設定されます。これは最も安全なオプションです。考慮すべき事項を以下に示します。

  • active/passive モードを使用している場合 (すべての Red Hat Single Sign-On サーバーは単一の site1 にあり、site2 の RHDG サーバーはバックアップとしてのみ使用されます。詳細は、「モード」 を参照してください。すべてのキャッシュを使用してパフォーマンスを保存するために、通常は ASYNC ストラテジーを使用するだけで十分です。
  • work キャッシュは、主に、キャッシュの無効化イベントなどの一部のメッセージを別のサイトに送信するために使用されます。また、userStorage 同期などの一部の特別なイベントが 1 つのサイトでのみ実行されるようにするためにも使用されます。このセットは SYNC のままにすることが推奨されます。
  • actionTokens キャッシュは、一部のトークン/チケットが一度だけ使用されたことを追跡するための 1 回限りのキャッシュとして使用されます。たとえば、アクショントークンまたは OAuth2 コードです。この設定を ASYNC に設定して、パフォーマンスを若干向上させることができますが、特定のチケットが実際に使用することは保証されません。たとえば、両方のサイトに同じチケットの同時リクエストがある場合は、両方のリクエストが ASYNC ストラテジーで成功する可能性があります。したがって、ここで設定する内容は、セキュリティー (SYNC ストラテジー) よりも優れたパフォーマンス (ASYNC ストラテジー) を使用するかどうかによって異なります。
  • loginFailures キャッシュは、3 つのモードのいずれかで使用できます。バックアップがまったくない場合は、ユーザーのログイン失敗の数がサイトごとに個別にカウントされることを意味します (詳細は 「Infinispan キャッシュ」 を参照)。これにはセキュリティー上の影響が一部でありますが、パフォーマンス上の利点がいくつかあります。また、サービス拒否攻撃 (DoS) 攻撃のリスクを軽減します。たとえば、攻撃者が両方のサイトでユーザーのユーザー名とパスワードを使用して 1000 個の同時要求をシミュレートする場合、サイト間で多くのメッセージが渡され、ネットワークの輻輳が生じる可能性があります。攻撃者の要求が他のサイトへのバックアップを待つことでブロックされず、ネットワークトラフィックがさらに混雑する可能性があるため、ASYNC ストラテジーはさらに悪化する可能性があります。また、ログイン失敗の数は ASYNC ストラテジーでは正確ではありません。

データセンター間のネットワークが遅い環境と、DoS の可能性を示す環境では、loginFailures キャッシュをまったくバックアップしないことが推奨されます。

  • SYNCsessions セッションおよび clientSessions セッションを保持することが推奨されます。ASYNC への切り替えは、ユーザー要求およびバックチャンネル要求 (「要求処理」 で説明されているように、クライアントアプリケーションから Red Hat Single Sign-On への要求) が常に同じサイトで処理されることが確実な場合に限り、可能です。これは、たとえば以下の場合に当てはまります。

    • 「モード」 で説明されているように active/passive モードを使用します。
    • すべてのクライアントアプリケーションが Red Hat Single Sign-On の JavaScript アダプター を使用している。JavaScript アダプターは、ブラウザー内でバックチャネル要求を送信するため、ブラウザーのスティッキーセッションに参加し、このユーザーの他のブラウザー要求と同じクラスターノード (つまり、同じサイト) で終了します。
    • ロードバランサーは、クライアント IP アドレス (場所) に基づいて要求に対応でき、クライアントアプリケーションは両方のサイトにデプロイされます。

      たとえば、LON と NYC の 2 つのサイトがあります。アプリケーションが LON サイトと NYC サイトの両方にデプロイされる限り、ロンドンユーザーからのすべてのユーザー要求が LON サイトのアプリケーションにリダイレクトされ、さらに LON サイトの Red Hat Single Sign-On サーバーにリダイレクトされるようにすることができます。LON サイトクライアントデプロイメントからのバックチャネル要求は、LON サイトの Red Hat Single Sign-On サーバーでも終了します。一方、アメリカのユーザー向けには、すべての Red Hat Single Sign-On リクエスト、アプリケーション要求、およびバックチャネル要求が NYC サイトで処理されます。

  • offlineSessions および offlineClientSessions の場合、クライアントアプリケーションにオフライントークンを使用する予定がない場合には、バックアップする必要がない点が異なります。

一般に、疑いがあり、パフォーマンスが妨げにならない場合は、キャッシュを SYNC ストラテジーで維持する方が安全です。

警告

SYNC/ASYNC バックアップへの切り替えについては、必ず backup 要素の strategy 属性を編集してください。以下に例を示します。

<backup site="site2" failure-policy="FAIL" strategy="ASYNC" enabled="true">

cache-configuration 要素の mode 属性に注意してください。

3.4.15. トラブルシューティング

トラブルシューティングが必要になった場合は、以下のヒントをご活用ください。

  • クロスサイトのレプリケーションの設定 の手順を実行し、これを最初に動作させることが推奨されます。これにより、その動作についてある程度理解することができます。また、このドキュメント全体を読んで、内容をある程度理解することも賢明です。
  • Red Hat Single Sign-On サーバーの場合は、サーバーの起動時に以下のようなメッセージが表示されます。

    18:09:30,156 INFO  [org.keycloak.connections.infinispan.DefaultInfinispanConnectionProviderFactory] (ServerService Thread Pool -- 54)
    Node name: node11, Site name: site1

    Red Hat Single Sign-On サーバーの起動時に、サイト名とノード名が想定どおりに表示されることを確認します。

  • 同じデータセンターからの Red Hat Single Sign-On サーバーのみが互いにクラスター内にあることを含め、Red Hat Single Sign-On サーバーが想定どおりにクラスターにあることを確認します。これは、GMS ビューを介して JConsole で確認することもできます。
  • Red Hat Single Sign-On サーバーの起動時に以下のような例外がある場合には、以下のようになります。

    17:33:58,605 ERROR [org.infinispan.client.hotrod.impl.operations.RetryOnFailureOperation] (ServerService Thread Pool -- 59) ISPN004007: Exception encountered. Retry 10 out of 10: org.infinispan.client.hotrod.exceptions.TransportException:: Could not fetch transport
    ...
    Caused by: org.infinispan.client.hotrod.exceptions.TransportException:: Could not connect to server: 127.0.0.1:12232
    	at org.infinispan.client.hotrod.impl.transport.tcp.TcpTransport.<init>(TcpTransport.java:82)

    通常、Red Hat Single Sign-On サーバーは、独自のデータセンター内で RHDG サーバーに到達できないことを意味します。ファイアウォールが想定どおりに設定され、RHDG サーバーが接続可能であることを確認します。

  • Red Hat Single Sign-On サーバーの起動時に以下のような例外がある場合には、以下のようになります。

    16:44:18,321 WARN  [org.infinispan.client.hotrod.impl.protocol.Codec21] (ServerService Thread Pool -- 57) ISPN004005: Error received from the server: javax.transaction.RollbackException: ARJUNA016053: Could not commit transaction.
     ...

    次に、サイトの対応する RHDG サーバーのログを確認して、他のサイトへのバックアップが失敗したかどうかを確認します。バックアップサイトが利用できない場合は、オフラインに切り替えることが推奨されます。これにより、RHDG サーバーがオフラインサイトにバックアップを試行せず、Red Hat Single Sign-On サーバー側でも操作が正常に渡されます。詳細は、「クロスサイトデプロイメントの管理」 を参照してください。

  • JMX 経由で利用できる Infinispan の統計を確認します。たとえば、ログインして、新しいセッションが両方の RHDG サーバーに正常に書き込まれ、そこの sessions キャッシュで利用可能かどうかを確認します。これは、sessions キャッシュ内の要素の数を MBean jboss.datagrid-infinispan:type=Cache,name="sessions(repl_sync)",manager="clustered",component=Statistics および numberOfEntries 属性に対してチェックして間接的に実行できます。ログイン後、両方のサイトの両方の RHDG サーバーに numberOfEntries のエントリーがもう 1 つあるはずです。
  • site1 の Red Hat Single Sign-On サーバーで user などのエンティティーを更新し、site2 の Red Hat Single Sign-On サーバーで更新されたエンティティーが見つからない場合、問題は同期データベース自体のレプリケーションまたは Red Hat Single Sign-On キャッシュが適切に無効になりません。ここ で説明するように、一時的に Red Hat Single Sign-On キャッシュを無効にして、問題がデータベースのレプリケーションレベルにある場合はダウンできます。また、手動でデータベースに接続し、データが想定どおりに更新されているかどうかを確認すると役立つ場合があります。これはすべてのデータベースに固有であるため、データベースのドキュメントを参照する必要があります。
  • RHDG サーバーログに、以下のようなロックに関連する例外が表示される場合があります。

    (HotRodServerHandler-6-35) ISPN000136: Error executing command ReplaceCommand,
    writing keys [[B0x033E243034396234..[39]]: org.infinispan.util.concurrent.TimeoutException: ISPN000299: Unable to acquire lock after
    0 milliseconds for key [B0x033E243034396234..[39] and requestor GlobalTx:server1:4353. Lock is held by GlobalTx:server1:4352

    これらの例外は必ずしも問題であるとは限りません。これらは、両方の DC で同じエンティティーの同時編集がトリガーされると、いつでも発生する可能性があります。これはデプロイメントでは一般的です。通常、Red Hat Single Sign-On サーバーは失敗した操作に関する通知を受け、再試行するため、ユーザーの観点からは、通常、問題はありません。

  • アプリケーションに対して Red Hat Single Sign-On で認証を試みても、ブラウザーでのリダイレクトの数が無限であるため認証が失敗し、Red Hat Single Sign-On サーバーログに以下のようなエラーが表示される場合は、以下のようになります。

    2017-11-27 14:50:31,587 WARN  [org.keycloak.events] (default task-17) type=LOGIN_ERROR, realmId=master, clientId=null, userId=null, ipAddress=aa.bb.cc.dd, error=expired_code, restart_after_timeout=true

    おそらく、スティッキーセッションをサポートするようにロードバランサーを設定する必要があることを意味します。Red Hat Single Sign-On サーバー (jboss.node.name プロパティー) の起動時に使用する指定のルート名に、現在のサーバーを識別するためにロードバランサーサーバーが使用する正しい名前が含まれていることを確認してください。

  • RHDG の work キャッシュが無期限に大きくなる場合は、こちらの RHDG の問題 が発生している可能性があります。これは、キャッシュ項目の有効期限が適切に切れていないことが原因で発生します。この場合、以下のように cache 宣言を空の <expiration /> タグで更新します。

        <replicated-cache name="work" configuration="sessions-cfg">
            <expiration />
        </replicated-cache>
  • RHDG サーバーログに以下のような警告が表示される場合は、

    18:06:19,687 WARN  [org.infinispan.server.hotrod.Decoder2x] (HotRod-ServerWorker-7-12) ISPN006011: Operation 'PUT_IF_ABSENT' forced to
      return previous value should be used on transactional caches, otherwise data inconsistency issues could arise under failure situations
    18:06:19,700 WARN  [org.infinispan.server.hotrod.Decoder2x] (HotRod-ServerWorker-7-10) ISPN006010: Conditional operation 'REPLACE_IF_UNMODIFIED' should
      be used with transactional caches, otherwise data inconsistency issues could arise under failure situations

    無視しても問題ありません。警告を回避するには、RHDG サーバー側のキャッシュをトランザクションキャッシュに変更することができますが、バグ https://issues.redhat.com/browse/ISPN-9323 により発生する他の問題が生じる可能性があるため、この方法は推奨されません。したがって、今のところ、警告は無視する必要があります。

  • RHDG サーバーログに以下のようなエラーが表示される場合、

    12:08:32,921 ERROR [org.infinispan.server.hotrod.CacheDecodeContext] (HotRod-ServerWorker-7-11) ISPN005003: Exception reported: org.infinispan.server.hotrod.InvalidMagicIdException: Error reading magic byte or message id: 7
    	at org.infinispan.server.hotrod.HotRodDecoder.readHeader(HotRodDecoder.java:184)
    	at org.infinispan.server.hotrod.HotRodDecoder.decodeHeader(HotRodDecoder.java:133)
    	at org.infinispan.server.hotrod.HotRodDecoder.decode(HotRodDecoder.java:92)
    	at io.netty.handler.codec.ByteToMessageDecoder.callDecode(ByteToMessageDecoder.java:411)
    	at io.netty.handler.codec.ByteToMessageDecoder.channelRead(ByteToMessageDecoder.java:248)

    また、Red Hat Single Sign-On ログに同様のエラーが表示される場合は、互換性のないバージョンの Hot Rod プロトコルが使用されていることを示している可能性があります。これは、古いバージョンの Infinispan サーバーで Red Hat Single Sign-On の使用を試みる際に発生する可能性があります。Red Hat Single Sign-On 設定ファイルの remote-store 要素に追加のプロパティーとして protocolVersion プロパティーを追加する場合に役立ちます。以下に例を示します。

    <property name="protocolVersion">2.6</property>

第4章 サブシステム設定の管理

Red Hat Single Sign-On の低レベル設定は、ディストリビューションの standalone.xml ファイル、standalone-ha.xml ファイル、または domain.xml ファイルを編集して行います。このファイルの場所は、操作モード によって異なります。

ここで設定できるエンドレス設定がありますが、本セクションは keycloak-server サブシステムの設定に重点を置いています。使用している設定ファイルに関係なく、keycloak-server サブシステムの設定は同じです。

keycloak-server サブシステムは通常、以下のようにファイルの最後の方で宣言されます。

<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
   <web-context>auth</web-context>
   ...
</subsystem>

このサブシステムで変更された変更は、サーバーが再起動されるまで反映されません。

4.1. SPI プロバイダーの設定

各設定の詳細については、その設定に関連する他の場所で説明します。ただし、SPI プロバイダーの設定を宣言するために使用される形式を理解しておくと便利です。

Red Hat Single Sign-On は、優れた柔軟性を可能にする高度なモジュールシステムです。50 を超えるサービスプロバイダーインターフェース (SPI) があり、各 SPI の実装をスワップアウトすることができます。SPI の実装は プロバイダー と呼ばれます。

SPI 宣言のすべての要素はオプションですが、完全な SPI 宣言は次のようになります。

<spi name="myspi">
    <default-provider>myprovider</default-provider>
    <provider name="myprovider" enabled="true">
        <properties>
            <property name="foo" value="bar"/>
        </properties>
    </provider>
    <provider name="mysecondprovider" enabled="true">
        <properties>
            <property name="foo" value="foo"/>
        </properties>
    </provider>
</spi>

2 つのプロバイダーが SPI myspi に定義されています。default-providermyprovider として一覧表示されます。ただし、この設定の処理方法は SPI が決定します。一部の SPI は複数のプロバイダーを許可し、一部は許可しません。そのため、default-provider は SPI の選択に役立ちます。

また、各プロバイダーは独自の設定プロパティーセットを定義することにも注意してください。上記の両方のプロバイダーに foo という名前のプロパティーがあるのは単なる偶然です。

各プロパティー値のタイプは、プロバイダーによって解釈されます。ただし、例外が 1 つあります。eventsStore SPI の jpa プロバイダーについて考えてみましょう。

<spi name="eventsStore">
    <provider name="jpa" enabled="true">
        <properties>
            <property name="exclude-events" value="[&quot;EVENT1&quot;,
                                                    &quot;EVENT2&quot;]"/>
        </properties>
    </provider>
</spi>

値が角括弧で始まり、角括弧で終わることがわかります。これは、値がリストとしてプロバイダーに渡されることを意味します。この例では、システムは 2 つの要素値 EVENT1 および EVENT2 を含む一覧をプロバイダーに渡します。リストに値をさらに追加するには、各リスト要素をコンマで区切ります。ただし、各リスト要素を囲む引用符は &quot; でエスケープする必要があります。

カスタムプロバイダーおよびプロバイダーの設定についての詳細は、『サーバー 開発者ガイド』 の手順に従います。

4.2. JBoss EAP CLI の起動

手動で設定を編集する以外に、jboss-cli ツールでコマンドを実行して設定を変更するオプションもあります。CLI を使用すると、サーバーをローカルまたはリモートで設定できます。また、スクリプトと組み合わせる場合に特に便利です。

JBoss EAP CLI を起動するには、jboss-cli を実行する必要があります。

Linux/Unix

$ .../bin/jboss-cli.sh

Windows

> ...\bin\jboss-cli.bat

これにより、以下のようなプロンプトが表示されます。

Prompt

[disconnected /]

実行中のサーバーでコマンドを実行する場合は、最初に connect コマンドを実行します。

connect

[disconnected /] connect
connect
[standalone@localhost:9990 /]

「ユーザー名やパスワードを入力していません!」と思っているかもしれません。スタンドアロンサーバーまたはドメインコントローラーと同じマシンで jboss-cli を実行し、アカウントに適切なファイルパーミッションがある場合は、管理者のユーザー名とパスワードを設定する必要がなくなります。この設定で不安定な場合、内容をより安全にする方法に関する詳細は、JBoss EAP の『設定ガイド』を参照してください。

4.3. CLI 組み込みモード

スタンドアロンサーバーと同じマシン上にあり、サーバーがアクティブでないときにコマンドを発行する場合は、サーバーを CLI に組み込み、着信要求を許可しない特別なモードで変更を加えることができます。これを実行するには、まず、変更する設定ファイルを指定して embed-server コマンドを実行します。

embed-server

[disconnected /] embed-server --server-config=standalone.xml
[standalone@embedded /]

4.4. CLI GUI モードの使用

CLI は GUI モードでも実行できます。GUI モードは、実行中 のサーバーの管理モデル全体をグラフィカルに表示および編集できる Swing アプリケーションを起動します。GUI モードは、CLI コマンドのフォーマット化や、使用可能なオプションの学習でサポートが必要な場合に特に便利です。GUI は、ローカルまたはリモートサーバーからサーバーログを取得することもできます。

手順

  1. GUI モードでの CLI の起動

    $ .../bin/jboss-cli.sh --gui

    注記: リモートサーバーに接続するには、--connect オプションも渡します。詳細は、--help オプションを使用します。

  2. 下にスクロールして、ノード subsystem=keycloak-server を見つけます。
  3. ノードを右クリックして、Explore subsystem=keycloak-server を選択します。

    新しいタブには、keycloak-server サブシステムのみが表示されます。

    keycloak-server サブシステム

    keycloak-server subsystem

4.5. CLI スクリプト

CLI には広範なスクリプト機能があります。スクリプトは、CLI コマンドを含むテキストファイルに過ぎません。テーマとテンプレートのキャッシュをオフにする単純なスクリプトについて考えてみましょう。

turn-off-caching.cli

/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheThemes,value=false)
/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheTemplates,value=false)

スクリプトを実行するには、CLI GUI の Scripts メニューに従うか、以下のようにコマンドラインからスクリプトを実行します。

$ .../bin/jboss-cli.sh --file=turn-off-caching.cli

4.6. CLI レシピ

いくつかの設定タスクと、CLI コマンドを使用してこれらを実行する方法を以下に説明します。最初の例では、ワイルドカードパス ** を使用して、置き換える必要があるか、keycloak-server サブシステムへのパスを使用します。

スタンドアロンの場合、これは単に次のことを意味します。

** = /subsystem=keycloak-server

ドメインモードの場合、これは次のような意味になります。

** = /profile=auth-server-clustered/subsystem=keycloak-server

4.6.1. サーバーの Web コンテキストの変更

/subsystem=keycloak-server/:write-attribute(name=web-context,value=myContext)

4.6.2. グローバルデフォルトテーマの設定

**/theme=defaults/:write-attribute(name=default,value=myTheme)

4.6.3. 新しい SPI とプロバイダーの追加

**/spi=mySPI/:add
**/spi=mySPI/provider=myProvider/:add(enabled=true)

4.6.4. プロバイダーの無効化

**/spi=mySPI/provider=myProvider/:write-attribute(name=enabled,value=false)

4.6.5. SPI のデフォルトプロバイダーの変更

**/spi=mySPI/:write-attribute(name=default-provider,value=myProvider)

4.6.6. dblock SPI の設定

**/spi=dblock/:add(default-provider=jpa)
**/spi=dblock/provider=jpa/:add(properties={lockWaitTimeout => "900"},enabled=true)

4.6.7. プロバイダーの単一プロパティー値の追加または変更

**/spi=dblock/provider=jpa/:map-put(name=properties,key=lockWaitTimeout,value=3)

4.6.8. プロバイダーからの単一プロパティーの削除

**/spi=dblock/provider=jpa/:map-remove(name=properties,key=lockRecheckTime)

4.6.9. Listタイプの provider プロパティーへの値の設定

**/spi=eventsStore/provider=jpa/:map-put(name=properties,key=exclude-events,value=[EVENT1,EVENT2])

第5章 プロファイル

Red Hat Single Sign-On には、デフォルトでは有効にされていない機能があります。これには、完全にサポートされていない機能が含まれます。さらに、デフォルトで有効になっている機能もいくつかありますが、無効にすることもできます。

有効および無効にできる機能は次のとおりです。

名前説明デフォルトでは有効サポートレベル

account2

新規アカウント管理コンソール

はい

サポート対象

account_api

アカウント管理 REST API

はい

サポート対象

admin_fine_grained_authz

きめ細かい管理パーミッション

いいえ

プレビュー

ciba

OpenID Connect Client Initiated Backchannel Authentication (CIBA)

はい

サポート対象

client_policies

クライアント設定ポリシーの追加

はい

サポート対象

client_secret_rotation

機密クライアントのクライアントシークレットのローテーションを有効にします。

はい

プレビュー

par

OAuth 2.0 Pushed Authorization Requests (PAR)

はい

サポート対象

declarative_user_profile

宣言型スタイルを使用したユーザープロファイルの設定

いいえ

プレビュー

docker

Docker レジストリープロトコル

いいえ

サポート対象

impersonation

管理者がユーザーを偽装する機能

はい

サポート対象

openshift_integration

OpenShift のセキュリティー保護を有効にするための拡張機能

いいえ

プレビュー

recovery_codes

認証のリカバリーコード

いいえ

プレビュー

scripts

JavaScript を使用したカスタムオーセンティケーターの作成

いいえ

プレビュー

step_up_authentication

段階的な認証

はい

サポート対象

token_exchange

トークン交換サービス

いいえ

プレビュー

upload_scripts

スクリプトのアップロード

いいえ

非推奨

web_authn

W3C Web Authentication (WebAuthn)

はい

サポート対象

update_email

Email ワークフローの更新

いいえ

プレビュー

すべてのプレビュー機能を有効にするには、以下を使用してサーバーを起動します。

bin/standalone.sh|bat -Dkeycloak.profile=preview

これを永続的に設定するには、standalone/configuration/profile.properties ファイル (ドメインモードの server-one の場合は domain/servers/server-one/configuration/profile.properties) を作成します。以下をファイルに追加します。

profile=preview

特定の機能を有効にするには、以下を使用してサーバーを起動します。

bin/standalone.sh|bat -Dkeycloak.profile.feature.<feature name>=enabled

たとえば、Docker を有効にするには -Dkeycloak.profile.feature.docker=enabled を使用します。

以下を追加すると、profile.properties ファイルでこれを永続的に設定できます。

feature.docker=enabled

特定の機能を無効にするには、以下を使用してサーバーを起動します。

bin/standalone.sh|bat -Dkeycloak.profile.feature.<feature name>=disabled

たとえば、Impersonation を無効にするには、-Dkeycloak.profile.feature.impersonation=disabled を使用します。

以下を追加すると、profile.properties ファイルでこれを永続的に設定できます。

feature.impersonation=disabled

第6章 リレーショナルデータベースの設定

Red Hat Single Sign-On には、H2 と呼ばれる独自の組み込み型 Java ベースのリレーショナルデータベースが同梱されています。これは、Red Hat Single Sign-On がデータを永続化するために使用するデフォルトのデータベースであり、実際には、認証サーバーをすぐに実行できるようにするためにのみ存在します。実稼働環境に対応した外部データベースに置き換えることを強くお勧めします。H2 データベースは、同時並行性の高い状況ではあまり実行可能ではないため、クラスターでも使用しないでください。この章では、Red Hat Single Sign-On をより成熟したデータベースに接続する方法を示すことを目的としています。

Red Hat Single Sign-On は、2 つの階層化テクノロジーを使用して、リレーショナルデータを永続化します。最下層にあるテクノロジーは JDBC です。JDBC は、RDBMS への接続に使用される Java API です。データベースベンダーが提供するデータベースのタイプごとに、異なる JDBC ドライバーがあります。この章では、これらのベンダー固有のドライバーの 1 つを使用するように Red Hat Single Sign-On を設定する方法について説明します。

永続性のための最上位の階層化テクノロジーは Hibernate JPAです。これは、Java オブジェクトをリレーショナルデータにマッピングするリレーショナルマッピング API のオブジェクトです。Red Hat Single Sign-On のほとんどのデプロイメントでは、Hibernate の設定要素を考慮する必要はありませんが、まれに実行する場合にこれがどのように実行されるかについて話していきます。

注記

データソース設定は、JBoss EAP『設定ガイド』「データソースの設定」の章で詳細に説明されています。

6.1. データベース設定チェックリスト

以下は、Red Hat Single Sign-On 用に RDBMS を設定するために実行する手順です。

  1. データベースの JDBC ドライバーを見つけてダウンロードします。
  2. ドライバー JAR をモジュールにパッケージ化し、このモジュールをサーバーにインストールします。
  3. サーバーの設定プロファイルで JDBC ドライバーを宣言します。
  4. データベースの JDBC ドライバーを使用するようにデータソース設定を変更します。
  5. データソース設定を変更して、データベースへの接続パラメーターを定義します。

本章では、そのすべての例に PostgresSQL を使用します。他のデータベースも同じ手順でインストールします。

6.2. JDBC ドライバーのパッケージ化

RDBMS の JDBC ドライバー JAR を見つけてダウンロードします。このドライバーを使用する前に、モジュールにパッケージ化してサーバーにインストールする必要があります。モジュールは、Red Hat Single Sign-On クラスパスにロードされる JAR と、それらの JAR が他のモジュールに持つ依存関係を定義します。

手順

  1. Red Hat Single Sign-On ディストリビューションの …​/modules/ ディレクトリー内に、モジュール定義を保持するためのディレクトリー構造を作成します。

    規則では、ディレクトリー構造の名前に JDBC ドライバーの Java パッケージ名を使用します。PostgreSQL の場合は、org/postgresql/main ディレクトリーを作成します。

  2. データベースドライバーの JAR をこのディレクトリーにコピーし、その中に空の module.xml ファイルを作成します。

    モジュールディレクトリー

    Module Directory

  3. module.xml ファイルを開き、次の XML を作成します。

    モジュール XML

    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.3" name="org.postgresql">
    
        <resources>
            <resource-root path="postgresql-VERSION.jar"/>
        </resources>
    
        <dependencies>
            <module name="javax.api"/>
            <module name="javax.transaction.api"/>
        </dependencies>
    </module>

    • モジュール名は、モジュールのディレクトリー構造と一致する必要があります。そのため、org/postgresqlorg.postgresql にマップします。
    • resource-root path 属性は、ドライバーの JAR ファイル名を指定する必要があります。
    • 残りは、JDBC ドライバー JAR が持つ通常の依存関係になります。

6.3. JDBC ドライバーの宣言とロード

JDBC をデプロイメントプロファイルに宣言すると、サーバーの起動時にロードされて使用可能になります。

前提条件

JDBC ドライバーをパッケージ化している。

手順

  1. デプロイメントモードに基づいてこれらのファイルの 1 つを編集し、JDBC ドライバーを宣言します。

    • スタンドアロンモードでは、…​/standalone/configuration/standalone.xml を編集します。
    • スタンドアロンクラスタリングモードでは、…​/standalone/configuration/standalone-ha.xml を編集します。
    • ドメインモードの場合は、…/domain/configuration/domain.xml を編集します。

      ドメインモードでは、auth-server-standalone または auth-server-clustered のうち、使用している方のプロファイルを編集する必要があります。

  2. プロファイルで datasources サブシステム内で drivers XML ブロックを検索します。

    H2 JDBC ドライバー用に宣言された事前定義されたドライバーが表示されるはずです。ここで、外部データベース用の JDBC ドライバーを宣言します。

    JDBC ドライバー

      <subsystem xmlns="urn:jboss:domain:datasources:6.0">
         <datasources>
           ...
           <drivers>
              <driver name="h2" module="com.h2database.h2">
                  <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
              </driver>
           </drivers>
         </datasources>
      </subsystem>

  3. drivers XML ブロック内で、追加の JDBC ドライバーを宣言します。

    • このドライバーに任意の name を割り当てます。
    • ドライバー JAR について以前に作成した module パッケージを参照する module 属性を指定します。
    • ドライバーの Java クラスを指定します。

      これは、この章で定義したモジュールの例に含まれる PostgreSQL ドライバーのインストール例です。

      JDBC ドライバーの宣言

        <subsystem xmlns="urn:jboss:domain:datasources:6.0">
           <datasources>
             ...
             <drivers>
                <driver name="postgresql" module="org.postgresql">
                    <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
                </driver>
                <driver name="h2" module="com.h2database.h2">
                    <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
                </driver>
             </drivers>
           </datasources>
        </subsystem>

6.4. Red Hat Single Sign-On データソースの変更

Red Hat Single Sign-On が新しい外部データベースに接続するために使用する既存のデータソース設定を変更します。これは、JDBC ドライバーを登録したものと同じ設定ファイルと XML ブロック内で行います。新しいデータベースへの接続を設定する例を以下に示します。

JDBC ドライバーの宣言

  <subsystem xmlns="urn:jboss:domain:datasources:6.0">
     <datasources>
       ...
       <datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true">
           <connection-url>jdbc:postgresql://localhost/keycloak</connection-url>
           <driver>postgresql</driver>
           <pool>
               <max-pool-size>20</max-pool-size>
           </pool>
           <security>
               <user-name>William</user-name>
               <password>password</password>
           </security>
       </datasource>
        ...
     </datasources>
  </subsystem>

前提条件

  • JDBC ドライバーはすでに宣言されています。

手順

  1. KeycloakDSdatasource 定義を検索します。

    最初に connection-url を変更する必要があります。ベンダーの JDBC 実装のドキュメントでは、この接続 URL 値の形式を指定する必要があります。

  2. 使用する driver を定義します。

    これは、この章の前のセクションで宣言した JDBC ドライバーの論理名です。

    トランザクションを実行するたびに、データベースへの新しい接続を開くにはコストがかかります。これを補うために、データソースの実装は開いている接続のプールを維持します。max-pool-size は、プールする接続の最大数を指定します。システムの負荷に応じて、この値を変更することをお勧めします。

  3. データベースへの接続に必要なデータベースのユーザー名とパスワードを定義します。この手順は、少なくとも PostgreSQL に必要です。この例では、クレデンシャルが明瞭なクリアテキストであることが懸念されるかもしれません。これらのクレデンシャルを難読化する方法は存在しますが、それはこのガイドの範囲を超えています。
注記

データソース機能の詳細は、JBoss EAP『設定ガイド』「データソースの設定」の章を参照してください。

6.5. データベースの設定

このコンポーネントの設定は、ディストリビューションの standalone.xml ファイル、standalone-ha.xml ファイル、または domain.xml ファイルにあります。このファイルの場所は、操作モード によって異なります。

データベース設定

<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
    ...
    <spi name="connectionsJpa">
     <provider name="default" enabled="true">
         <properties>
             <property name="dataSource" value="java:jboss/datasources/KeycloakDS"/>
             <property name="initializeEmpty" value="false"/>
             <property name="migrationStrategy" value="manual"/>
             <property name="migrationExport" value="${jboss.home.dir}/keycloak-database-update.sql"/>
         </properties>
     </provider>
    </spi>
    ...
</subsystem>

可能な設定オプションは以下のとおりです。

dataSource
dataSource の JNDI 名
jta
データソースが JTA 対応かどうかを指定するブール値プロパティー
driverDialect
データベース方言の値。ほとんどの場合、方言は Hibernate によって自動検出されるため、このプロパティーを指定する必要はありません。
initializeEmpty
空の場合はデータベースを初期化します。false に設定する場合は、データベースを手動で初期化する必要があります。データベースを手動で初期化する場合は、migrationStrategy を 手動 に設定して、データベースを初期化する SQL コマンドを含むファイルを作成します。デフォルトは true です。
migrationStrategy
データベースの移行に使用するストラテジー。有効な値は、updatemanual、および validate です。更新により、データベーススキーマが自動的に移行されます。Manual は、データベースで手動で実行できる SQL コマンドを使用して、必要な変更をファイルにエクスポートします。Validate は、データベースが最新であるかどうかを確認します。
migrationExport
手動のデータベース初期化/移行ファイルを書き込む場所のパス。
showSql
Hibernate がコンソールのすべての SQL コマンドを表示するかどうかを指定します (デフォルトは false)。これは非常に詳細です!
formatSql
Hibernate が SQL コマンドをフォーマットするかどうかを指定します (デフォルトは true)。
globalStatsInterval
実行された DB クエリーなどに関する Hibernate からのグローバル統計をログに記録します。統計は指定の間隔 (秒単位) でサーバーログに常に報告され、各レポートの後に消去されます。
schema
使用するデータベーススキーマを指定します。
注記

これらの設定スイッチの詳細は、JBoss EAP の 『開発ガイド』を参照してください。

6.6. データベースの Unicode の考慮事項

Red Hat Single Sign-On のデータベーススキーマは、以下の特別なフィールドの Unicode 文字列のみを考慮します。

  • レルム: 表示名、HTML 表示名、ローカリゼーションテキスト(キーと値)
  • フェデレーションプロバイダー: 表示名
  • ユーザー: ユーザー名、名、姓、属性名、および値
  • グループ: 名前、属性名、値
  • ロール: 名前
  • オブジェクトの説明

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

データベースによっては、Unicode 文字を処理できるようにするには、データベースや JDBC ドライバーに特別な設定が必要になります。データベースの設定は、以下で確認してください。データベースがここにリストされている場合には、データベースと JDBC ドライバーのレベルの両方で UTF-8 エンコーディングを適切に処理できます。

技術的には、すべてのフィールドの Unicode サポートの主な基準は、データベースが VARCHAR フィールドおよび CHAR フィールドに Unicode 文字セットを設定することができるかどうかです。yes の場合、通常はフィールドの長さが入念される可能性が高くなっています。NVARCHAR フィールドおよび NCHAR フィールドでのみ Unicode をサポートしているのであれば、Keycloak スキーマは VARCHAR フィールドおよび CHAR フィールドを広範囲に使用しているため、すべてのテキストフィールドで Unicode サポートしていることはおそらくありません。

6.6.1. Oracle データベース

データベースが VARCHAR フィールドおよび CHAR フィールドで Unicode サポートをサポートして作成されている場合 (AL32UTF8 文字セットをデータベースの文字セットとして使用するなど)、Unicode 文字は適切に処理されます。JDBC ドライバーには特別な設定は必要ありません。

データベース文字セットが Unicode でない場合、特殊フィールドに Unicode 文字を使用するには、接続プロパティー oracle.jdbc.defaultNChartrue に設定して JDBC ドライバーを設定する必要があります。厳密には必要ありませんが、oracle.jdbc.convertNcharLiterals 接続プロパティーを true に設定することが適している場合があります。これらのプロパティーはシステムプロパティーまたは接続プロパティーとして設定できます。oracle.jdbc.defaultNChar の設定は、パフォーマンスに悪い影響を及ぼす可能性があることに注意してください。詳細は、Oracle JDBC ドライバーの設定に関するドキュメントを参照してください。

6.6.2. Microsoft SQL Server データベース

Unicode 文字は、特別なフィールドに対してのみ適切に処理されます。JDBC ドライバーまたはデータベースの特別な設定は必要ありません。

6.6.3. MySQL データベース

データベースが、CREATE DATABASE コマンドの VARCHAR フィールドおよび CHAR フィールドで Unicode サポートをサポートして作成されている場合は、Unicode 文字が適切に処理されます (utf8 文字セットを MySQL 5.5 のデフォルトのデータベースの文字セットとして使用するなど。utf8 文字セットのストレージ要件が異なるため、utf8mb4 文字セットが機能しないことに注意してください [1])。この場合、特定の文字数に対応するために列が作成されてバイトではなく、特別なフィールドへの長さの制限が適用されることに注意してください。データベースのデフォルト文字セットで Unicode を保存できない場合、特別なフィールドのみが Unicode 値を格納できます。

JDBC ドライバー設定で、接続プロパティー characterEncoding=UTF-8 を JDBC 接続設定に追加する必要があります。

6.6.4. PostgreSQL データベース

Unicode は、データベースの文字セットが UTF8 の場合にサポートされます。この場合、Unicode 文字をいずれかのフィールドに使用できますが、特別なフィールド以外のフィールドの長さが削減されません。JDBC ドライバーの特別な設定は必要ありません。

PostgreSQL データベースの文字セットは、作成時に決定されます。SQL コマンドを使用して、PostgreSQL クラスターのデフォルトの文字セットを決定できます。

show server_encoding;

デフォルトの文字セットが UTF 8 ではない場合、以下のように UTF8 を文字セットとして使用してデータベースを作成できます。

create database keycloak with encoding 'UTF8';

第7章 パブリックホスト名の使用

Red Hat Single Sign-On では、パブリックのホスト名を使用します。たとえば、トークン発行者フィールドおよび URL で、パスワードリセットメールで送信されます。

Hostname SPI は、要求のホスト名の設定方法を提供します。初期状態のプロバイダーでは、フロントエンドリクエストの固定 URL を設定し、バックエンド要求をリクエスト URI を基にすることを許可します。組み込みプロバイダーが必要な機能を提供しない場合に、独自のプロバイダーを開発することもできます。

7.1. デフォルトのプロバイダー

デフォルトのホスト名プロバイダーは、設定された frontendUrl をフロントエンド要求のベース URL (ユーザーエージェントからの要求) として使用し、バックエンド要求のベースとして URL を使用します (クライアントからの直接要求)。

frontend の要求は、Keycloak サーバーと同じ context-path を持つ必要はありません。これは、https://auth.example.orghttps://example.org/keycloak などのように Keycloak を公開することができますが、内部的には、URL が https://10.0.0.10:8080/auth になる可能性があります。

これにより、ユーザーエージェント (ブラウザー) がパブリックドメイン名を介して Red Hat Single Sign-On にリクエストを送信できますが、内部クライアントは内部ドメイン名または IP アドレスを使用できます。

これは OpenID Connect Discovery エンドポイントに反映されます。たとえば、authorization_endpoint はフロントエンド URL を使用し、token_endpoint はバックエンド URL を使用します。ここでは、インスタンスのパブリッククライアントはパブリックエンドポイント経由で Keycloak と通信するため、authorization_endpointtoken_endpoint のベースが同じになります。

Keycloak の frontendUrl を設定するには、-Dkeycloak.frontendUrl=https://auth.example.org をスタートアップに渡すか、standalone.xml で設定できます。以下の例を参照してください。

<spi name="hostname">
    <default-provider>default</default-provider>
    <provider name="default" enabled="true">
        <properties>
            <property name="frontendUrl" value="https://auth.example.com"/>
            <property name="forceBackendUrlToFrontendUrl" value="false"/>
        </properties>
    </provider>
</spi>

jboss-cli で frontendUrl を更新するには、次のコマンドを使用します。

/subsystem=keycloak-server/spi=hostname/provider=default:write-attribute(name=properties.frontendUrl,value="https://auth.example.com")

すべてのリクエストがパブリックドメイン名を通過する必要がある場合は、forceBackendUrlToFrontendUrltrue に設定すると、バックエンドリクエストもフロントエンド URL を強制的に使用させることができます。

個々のレルムのデフォルトのフロントエンド URL を上書きすることもできます。これは管理コンソールで実行できます。

管理エンドポイントおよびコンソールをパブリックドメインに公開しない場合は、adminUrl プロパティーを使用して管理コンソールの固定 URL を設定します。これは frontendUrl とは異なります。また、/auth/admin へのアクセスを外部でブロックする必要があります。詳細は、『サーバー 管理ガイド』 を参照してください。

7.2. カスタムプロバイダー

カスタムホスト名プロバイダーを開発するには、org.keycloak.urls.HostnameProviderFactory および org.keycloak.urls.HostnameProvider を実装する必要があります。

カスタムプロバイダーの開発方法は、『サーバー開発者 ガイド』 の「サービスプロバイダーインターフェース」セクションを参照してください。

第8章 ネットワークの設定

Red Hat Single Sign-On のデフォルトインストールは、いくつかのネットワーク制限付きで実行できます。1 つは、すべてのネットワークエンドポイントが localhost にバインドされるため、認証サーバーは実際には 1 つのローカルマシンでのみ使用可能です。HTTP ベースの接続では、80 や 443 などのデフォルトポートを使用しません。HTTPS/SSL は追加設定なしでは設定されず、Red Hat Single Sign-On には多くのセキュリティー脆弱性があります。最後に、Red Hat Single Sign-On は、外部サーバーへのセキュアな SSL および HTTPS 接続を作成する必要があるため、エンドポイントを正しく検証できるようにトラストストアを設定する必要があります。本章では、これらすべてについて説明します。

8.1. バインドアドレス

デフォルトでは、Red Hat Single Sign-On は localhost ループバックアドレス 127.0.0.1 にバインドされます。これは、認証サーバーがネットワークで利用可能な場合に非常に便利なデフォルトではありません。通常、パブリックネットワークにリバースプロキシーまたはロードバランサーをデプロイし、トラフィックをプライベートネットワーク上に個別の Red Hat Single Sign-On サーバーインスタンスにルーティングすることが推奨されます。ただし、いずれの場合も、localhost 以外のインターフェースにバインドするようにネットワークインターフェースを設定する必要があります。

バインドアドレスの設定は非常に簡単で、「操作モードでの選択」 の章で説明されているとおり、コマンドラインでブートスクリプト standalone.sh または domain.sh のいずれかを使用して実行できます。

$ standalone.sh -b 192.168.0.5

-b スイッチは、任意のパブリックインターフェースの IP バインドアドレスを設定します。

または、コマンドラインでバインドアドレスを設定したくない場合は、デプロイメントのプロファイル設定を編集することもできます。プロファイル設定ファイル (操作モード に応じて standalone.xml または domain.xml) を開き、interfaces XML ブロックを探します。

    <interfaces>
        <interface name="management">
            <inet-address value="${jboss.bind.address.management:127.0.0.1}"/>
        </interface>
        <interface name="public">
            <inet-address value="${jboss.bind.address:127.0.0.1}"/>
        </interface>
    </interfaces>

public インターフェースは、公開されているソケットを作成するサブシステムに対応します。これらのサブシステムの 1 つが、Red Hat Single Sign-On の認証エンドポイントを提供する Web レイヤーです。management インターフェースは、JBoss EAP の管理レイヤーによって開かれたソケットに対応します。具体的には、jboss-cli.sh コマンドラインインターフェースと JBoss EAP Web コンソールを使用できるようにするソケットです。

public インターフェースを確認すると、特別な文字列 ${jboss.bind.address:127.0.0.1} があることを確認できます。この文字列は、Java システムプロパティーを設定してコマンドラインで上書きできる値 127.0.0.1 を示します。

$ domain.sh -Djboss.bind.address=192.168.0.5

-b は、このコマンドの簡単な表記です。そのため、バインドアドレス値をプロファイル設定で直接変更したり、起動時にコマンドラインで変更することができます。

注記

インターフェース の定義を設定する際には、さらに多くのオプションを利用できます。詳細は、JBoss EAP『設定ガイド』の「ネットワークインターフェース」を参照してください。

8.2. ソケットポートバインディング

各ソケットに対して開いているポートには、コマンドラインまたは設定内で上書きできる事前定義済みポートがあります。この設定を説明するために、スタンドアロンモード で実行していると仮定して、…​/standalone/configuration/standalone.xml を開きます。socket-binding-group を検索します。

    <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
        <socket-binding name="management-http" interface="management" port="${jboss.management.http.port:9990}"/>
        <socket-binding name="management-https" interface="management" port="${jboss.management.https.port:9993}"/>
        <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
        <socket-binding name="http" port="${jboss.http.port:8080}"/>
        <socket-binding name="https" port="${jboss.https.port:8443}"/>
        <socket-binding name="txn-recovery-environment" port="4712"/>
        <socket-binding name="txn-status-manager" port="4713"/>
        <outbound-socket-binding name="mail-smtp">
            <remote-destination host="localhost" port="25"/>
        </outbound-socket-binding>
    </socket-binding-group>

socket-bindings は、サーバーによって開かれるソケット接続を定義します。これらのバインディングは、使用する インターフェース (バインドアドレス) と、開くポート番号を指定します。最も関心が高いと思われるものは、以下のとおりです。

http
Red Hat Single Sign-On HTTP 接続に使用するポートを定義します。
https
Red Hat Single Sign-On HTTPS 接続に使用されるポートを定義します。
ajp
このソケットバインディングは、AJP プロトコルに使用されるポートを定義します。このプロトコルは、Apache HTTPD をロードバランサーとして使用する場合に mod-cluster とともに Apache HTTPD サーバーによって使用されます。
management-http
JBoss EAP CLI および Web コンソールによって使用される HTTP 接続を定義します。

ドメインモード で実行している場合は、例の domain.xml ファイルに複数の socket-binding-groups が定義されているため、ソケット構成の設定は若干複雑になります。server-group 定義までスクロールダウンすると、各 server-group に使用される socket-binding-group を確認できます。

ドメインソケットバインディング

    <server-groups>
        <server-group name="load-balancer-group" profile="load-balancer">
            ...
            <socket-binding-group ref="load-balancer-sockets"/>
        </server-group>
        <server-group name="auth-server-group" profile="auth-server-clustered">
            ...
            <socket-binding-group ref="ha-sockets"/>
        </server-group>
    </server-groups>

注記

socket-binding-group 定義を設定する際に、さらに多くのオプションを利用できます。詳細は、JBoss EAP『設定ガイド』の「ソケットバインディンググループ」を参照してください。

8.3. HTTPS/SSL の設定

警告

Red Hat Single Sign-On は、SSL/HTTPS を処理するようにデフォルトで設定されていません。Red Hat Single Sign-On サーバー自体で SSL を有効にするか、Red Hat Single Sign-On サーバーの前のリバースプロキシーで SSL を有効にすることを強くお勧めします。

このデフォルトの動作は、各 Red Hat Single Sign-On レルムの SSL/HTTPS モードによって定義されます。詳細は、『サーバー 管理ガイド』 で詳しく説明していますが、コンテキストとこれらのモードの概要を説明します。

外部要求
localhost127.0.0.110.x.x.x,192.168.x.x172.16.x.x などのプライベート IP アドレスに限り、Red Hat Single Sign-On は SSL なしで追加できます。サーバーに SSL/HTTPS が設定されていない場合や、非プライベート IP アドレスから HTTP 経由で Red Hat Single Sign-On にアクセスしようとすると、エラーが発生します。
なし
Red Hat Single Sign-On には SSL は必要ありません。これは、処理を実行し、この開発でのみ使用する必要があります。
すべてのリクエスト
Red Hat Single Sign-On では、すべての IP アドレスに SSL が必要です。

各レルムの SSL モードは、Red Hat Single Sign-On の管理コンソールで設定できます。

8.3.1. Red Hat Single Sign-On サーバーの SSL/HTTPS の有効化

リバースプロキシーまたはロードバランサーを使用して HTTPS トラフィックを処理する場合、Red Hat Single Sign-On サーバーの HTTPS を有効にする必要があります。以下が関与します。

  1. SSL/HTTP トラフィック用の秘密鍵と証明書が含まれるキーストアの取得または生成
  2. このキーペアと証明書を使用するように Red Hat Single Sign-On サーバーを設定します。

8.3.1.1. 証明書および Java キーストアの作成

HTTPS 接続を許可するには、Red Hat Single Sign-On サーバーをデプロイする Web コンテナーで HTTPS を有効にする前に、自己署名またはサードパーティーの署名済み証明書を取得し、Java キーストアにインポートする必要があります。

8.3.1.1.1. 自己署名証明書

開発時には、Red Hat Single Sign-On デプロイメントをテストするためにサードパーティーの署名済み証明書がなくても、Java JDK に同梱される keytool ユーティリティーを使用して自己署名証明書を生成する必要があります。

$ keytool -genkey -alias localhost -keyalg RSA -keystore keycloak.jks -validity 10950
    Enter keystore password: secret
    Re-enter new password: secret
    What is your first and last name?
    [Unknown]:  localhost
    What is the name of your organizational unit?
    [Unknown]:  Keycloak
    What is the name of your organization?
    [Unknown]:  Red Hat
    What is the name of your City or Locality?
    [Unknown]:  Westford
    What is the name of your State or Province?
    [Unknown]:  MA
    What is the two-letter country code for this unit?
    [Unknown]:  US
    Is CN=localhost, OU=Keycloak, O=Test, L=Westford, ST=MA, C=US correct?
    [no]:  yes

What is your first and last name ? の質問が表示されたら、サーバーをインストールするマシンの DNS 名を提供します。テストの目的では、localhost を使用する必要があります。このコマンドを実行すると、keycloak.jks ファイルが keytool コマンドの実行と同じディレクトリーに生成されます。

サードパーティーの署名済み証明書が必要で、証明書がない場合は、cacert.org で無料の証明書を取得できます。ただし、最初に次の手順を使用する必要があります。

手順

  1. 証明書要求を生成します。

    $ keytool -certreq -alias yourdomain -keystore keycloak.jks > keycloak.careq

    yourdomain は、この証明書が生成される DNS 名に置き換えます。keytool は要求を生成します。

    -----BEGIN NEW CERTIFICATE REQUEST-----
    MIIC2jCCAcICAQAwZTELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAk1BMREwDwYDVQQHEwhXZXN0Zm9y
    ZDEQMA4GA1UEChMHUmVkIEhhdDEQMA4GA1UECxMHUmVkIEhhdDESMBAGA1UEAxMJbG9jYWxob3N0
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr7kck2TaavlEOGbcpi9c0rncY4HhdzmY
    Ax2nZfq1eZEaIPqI5aTxwQZzzLDK9qbeAd8Ji79HzSqnRDxNYaZu7mAYhFKHgixsolE3o5Yfzbw1
    29RvyeUVe+WZxv5oo9wolVVpdSINIMEL2LaFhtX/c1dqiqYVpfnvFshZQaIg2nL8juzZcBjj4as
    H98gIS7khql/dkZKsw9NLvyxgJvp7PaXurX29fNf3ihG+oFrL22oFyV54BWWxXCKU/GPn61EGZGw
    Ft2qSIGLdctpMD1aJR2bcnlhEjZKDksjQZoQ5YMXaAGkcYkG6QkgrocDE2YXDbi7GIdf9MegVJ35
    2DQMpwIDAQABoDAwLgYJKoZIhvcNAQkOMSEwHzAdBgNVHQ4EFgQUQwlZJBA+fjiDdiVzaO9vrE/i
    n2swDQYJKoZIhvcNAQELBQADggEBAC5FRvMkhal3q86tHPBYWBuTtmcSjs4qUm6V6f63frhveWHf
    PzRrI1xH272XUIeBk0gtzWo0nNZnf0mMCtUBbHhhDcG82xolikfqibZijoQZCiGiedVjHJFtniDQ
    9bMDUOXEMQ7gHZg5q6mJfNG9MbMpQaUVEEFvfGEQQxbiFK7hRWU8S23/d80e8nExgQxdJWJ6vd0X
    MzzFK6j4Dj55bJVuM7GFmfdNC52pNOD5vYe47Aqh8oajHX9XTycVtPXl45rrWAH33ftbrS8SrZ2S
    vqIFQeuLL3BaHwpl3t7j2lMWcK1p80laAxEASib/fAwrRHpLHBXRcq6uALUOZl4Alt8=
    -----END NEW CERTIFICATE REQUEST-----
  2. この CA 要求を認証局 (CA) に送信します。

    CA は署名済み証明書を発行して送信します。

  3. CA のルート証明書を取得してインポートします。

    CA (root.crt) から証明書をダウンロードし、以下のようにインポートすることができます。

    $ keytool -import -keystore keycloak.jks -file root.crt -alias root
  4. 新しい CA が生成した証明書をキーストアにインポートします。

    $ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificate.cer

8.3.1.2. キーストアを使用するように Red Hat Single Sign-On を設定する

適切な証明書を持つ Java キーストアを利用したので、Red Hat Single Sign-On インストールを使用するように設定する必要があります。

手順

  1. キーストアを使用し、HTTPS を有効にするには、standalone.xml ファイル、standalone-ha.xml ファイル、または host.xml ファイルを編集する必要があります。
  2. キーストアファイルをデプロイメントの configuration/ ディレクトリーに移動するか、または選択した場所のファイルに移動して、そのファイルへの絶対パスを指定することができます。

    絶対パスを使用している場合は、設定から任意の relative-to パラメーターを削除します (操作モード を参照してください)。

  3. CLI を使用してキーストアを設定します。

    $ /subsystem=elytron/key-store=httpsKS:add(relative-to=jboss.server.config.dir,path=keycloak.jks,credential-reference={clear-text=secret},type=JKS)
    $ /subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS,credential-reference={clear-text=secret})
    $ /subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=httpsKM,protocols=[\"TLSv1.3\"])

    ドメインモードを使用する場合、コマンドは /host=<host_name>/ 接頭辞を使用するすべてのホストで実行する必要があります (すべてのホストで security-realm を作成するため)。これは、ホストごとに繰り返す例です。

    $ /host=<host_name>/subsystem=elytron/key-store=httpsKS:add(relative-to=jboss.server.config.dir,path=keycloak.jks,credential-reference={clear-text=secret},type=JKS)
  4. https-listener を変更して、以前に作成した 'server-ssl-context' を使用します。

    $ /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context, value=httpsSSC)

    ドメインモードを使用している場合は、コマンドの前に /profile=<profile_name>/ で使用されている使用されるプロファイルを付けます。

    生成される要素である server name="default-server" (subsystem xmlns="urn:jboss:domain:undertow:12.0" の子要素) には以下のスタンザを含める必要があります。

    <subsystem xmlns="urn:jboss:domain:undertow:12.0">
       <buffer-cache name="default"/>
       <server name="default-server">
          <https-listener name="https" socket-binding="https" ssl-context="httpsSSC"/>
       ...
    </subsystem>

TLS の設定に関する詳細は、WildFly のドキュメント を参照してください

8.4. 送信 HTTP 要求

Red Hat Single Sign-On サーバーは、アプリケーションに対してブラウザー以外の HTTP 要求を保護する必要があります。認証サーバーは、HTTP クライアント接続プールを維持し、これらの発信接続を管理します。standalone.xmlstandalone-ha.xml、または domain.xml で設定する必要があります。このファイルの場所は、操作モード によって異なります。

HTTP クライアント設定例

<spi name="connectionsHttpClient">
    <provider name="default" enabled="true">
        <properties>
            <property name="connection-pool-size" value="256"/>
        </properties>
    </provider>
</spi>

可能な設定オプションは以下のとおりです。

establish-connection-timeout-millis
ソケット接続の確立のタイムアウト。
socket-timeout-millis
発信リクエストがこの期間のデータを受信しない場合は、接続をタイムアウトします。
connection-pool-size
プールで使用できる接続数 (デフォルトは 128)。
max-pooled-per-route
ホストごとにプールできる接続の数 (デフォルトでは 64)。
connection-ttl-millis
最大接続時間 (ミリ秒単位)。デフォルトでは設定されません。
max-connection-idle-time-millis
接続プールで接続がアイドル状態でいられる最大期間 (デフォルトでは900 秒)。Apache HTTP クライアントのバックグラウンドクリーナースレッドを開始します。このチェックとバックグラウンドスレッドを無効にするには、-1 に設定します。
disable-cookies
デフォルトは true です。true に設定すると、クッキーキャッシングは無効になります。
client-keystore
これは、Java キーストアファイルへのパスです。このキーストアには双方向 SSL のクライアント証明書が含まれます。
client-keystore-password
クライアントキーストアのパスワード。これは、client-keystore が設定されている場合は 必須 になります。
client-key-password
クライアントのキーのパスワードこれは、client-keystore が設定されている場合は 必須 になります。
proxy-mappings
送信 HTTP 要求のプロキシー設定を示します。詳細は、Proxy Mappings for Outgoing HTTP Requests のセクションを参照してください。
disable-trust-manager
発信要求に HTTPS が必要で、この設定オプションが true に設定されている場合は、トラストストアを指定する必要がありません。この設定は開発時のみ使用してください。これは SSL 証明書の検証を無効にするため、実稼働環境では 使用しないで ください。これは 任意 です。デフォルト値は false です。

8.4.1. HTTP 要求の送信プロキシーマッピング

Red Hat Single Sign-On によって送信される送信 HTTP 要求は、任意でプロキシーマッピングのコンマ区切りリストに基づいてプロキシーサーバーを使用できます。プロキシーマッピングは、hostnamePattern;proxyUri の形式で、正規表現ベースのホスト名パターンとプロキシー URI の組み合わせを示します。以下に例を示します。

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

送信 HTTP リクエストのプロキシーを決定するには、ターゲットのホスト名が、設定されたホスト名パターンと照合されます。最初のマッチングパターンは、使用する proxy-uri を決定します。指定のホスト名に対して設定されたパターンのいずれも一致しない場合は、プロキシーは使用されません。

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

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

proxy-uri の特別な値 NO_PROXY は、関連付けられたホスト名パターンに一致するホストにプロキシーを使用すべきではないことを示すために使用できます。proxy-mappings の最後に catch-all パターンを指定して、すべての送信リクエストにデフォルトのプロキシーを定義することができます。

proxy-mapping の設定の例を以下に示します。

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

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

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

これは、以下の jboss-cli コマンドで設定できます。以下のように regex-pattern を適切にエスケープする必要があります。

echo SETUP: Configure proxy routes for HttpClient SPI

# In case there is no connectionsHttpClient definition yet
/subsystem=keycloak-server/spi=connectionsHttpClient/provider=default:add(enabled=true)

# Configure the proxy-mappings
/subsystem=keycloak-server/spi=connectionsHttpClient/provider=default:write-attribute(name=properties.proxy-mappings,value=[".*\\.(google|googleapis)\\.com;http://www-proxy.acme.com:8080",".*\\.acme\\.com;NO_PROXY",".*;http://fallback:8080"])

jboss-cli コマンドを実行すると、以下のサブシステムが設定されます。&quot;" 文字をエンコードする必要があることに注意してください。

<spi name="connectionsHttpClient">
    <provider name="default" enabled="true">
        <properties>
            <property
            name="proxy-mappings"
            value="[&quot;.*\\.(google|googleapis)\\.com;http://www-proxy.acme.com:8080&quot;,&quot;.*\\.acme\\.com;NO_PROXY&quot;,&quot;.*;http://fallback:8080&quot;]"/>
        </properties>
    </provider>
</spi>

8.4.2. 標準の環境変数の使用

または、標準の環境変数を使用して、プロキシーマッピング( HTTP_PROXYHTTPS_PROXY、および NO_PROXY 変数)を設定できます。

HTTP_PROXY および HTTPS_PROXY 変数は、すべての送信 HTTP 要求に使用されるプロキシーサーバーを表します。Red Hat Single Sign-On は、この 2 つのものとは変わりません。両方が指定されている場合、HTTPS_PROXY はプロキシーサーバーが使用する実際のスキームに関係なく優先されます。

NO_PROXY 変数は、プロキシーを使用しないホスト名のコンマ区切りリストを定義するために使用されます。ホスト名が指定されている場合、その接頭辞(subdomains)もプロキシーの使用から除外されます。

以下の例を使用します。

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

この例では、すべての送信 HTTP リクエストは、login.google.comgoogle.comauth.login.facebook.com などのリクエストを除き、https://www-proxy.acme.com:8080 プロキシーサーバーを使用します。たとえば、groups.facebook.com はプロキシー経由でルーティングされます。

注記

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

(上記のように)プロキシーマッピングがサブシステム設定を使用して定義される場合、環境変数は Red Hat Single Sign-On によって考慮されません。HTTP_PROXY 環境変数が定義されていても、プロキシーサーバーを使用しない場合は、このシナリオが適用されます。これを実行するには、以下のように汎用のプロキシールートを指定します。

<spi name="connectionsHttpClient">
    <provider name="default" enabled="true">
        <properties>
            <property name="proxy-mappings" value=".*;NO_PROXY"/>
        </properties>
    </provider>
</spi>

8.4.3. 送信 HTTPS リクエストトラストストア

Red Hat Single Sign-On がリモート HTTPS エンドポイントで呼び出される場合、信頼できるサーバーに接続するためにリモートサーバーの証明書を検証する必要があります。これは、中間者攻撃を防ぐために必要です。これらの証明書を署名したこれらのリモートサーバーまたは CA の証明書はトラストストアに配置する必要があります。このトラストストアは、Red Hat Single Sign-On サーバーによって管理されます。

トラストストアは、アイデンティティーブローカー、LDAP アイデンティティープロバイダーに安全を接続する際に使用され、電子メールの送信時やクライアントアプリケーションとのバックチャネル通信に使用されます。

警告

デフォルトでは、トラストストアプロバイダーは設定されず、https 接続は Java の JSSE リファレンスガイド で説明されているように、標準の Javaトラストストア設定にフォールバックします。信頼が確立されていない場合、これらの発信 HTTPS リクエストは失敗します。

keytool を使用して新しいトラストストアファイルを作成したり、信頼されるホスト証明書を既存のホスト証明書に追加したりできます。

$ keytool -import -alias HOSTDOMAIN -keystore truststore.jks -file host-certificate.cer

トラストストアは、ディストリビューションの standalone.xml ファイル、standalone-ha.xml ファイル、または domain.xml ファイル内で設定されます。このファイルの場所は、操作モード によって異なります。以下のテンプレートを使用して、トラストストア設定を追加できます。

<spi name="truststore">
    <provider name="file" enabled="true">
        <properties>
            <property name="file" value="path to your .jks file containing public certificates"/>
            <property name="password" value="password"/>
            <property name="hostname-verification-policy" value="WILDCARD"/>
        </properties>
    </provider>
</spi>

この設定の可能な設定オプションは以下のとおりです。

file
Java キーストアファイルへのパス。HTTPS 要求は、通信しているサーバーのホストを確認する方法が必要です。これは、トラストストアが行なうことです。キーストアには、1 つ以上の信頼できるホスト証明書または認証局が含まれます。このトラストストアファイルには、セキュアなホストのパブリック証明書のみを含める必要があります。これは、これらのプロパティーのいずれかが定義されている場合には 必須 になります。
password
キーストアのパスワード。これは、これらのプロパティーのいずれかが定義されている場合には 必須 になります。
hostname-verification-policy
デフォルト では WILDCARD です。HTTPS 要求の場合、これによりサーバーの証明書のホスト名が検証されます。ANY は、ホスト名が検証されていないことを意味します。WILDCARD *.foo.com などのサブドメイン名のワイルドカードを許可します。STRICT CN はホスト名に完全に一致する必要があります。

第9章 Red Hat Single Sign-On をクラスターで実行するための設定

クラスターで実行するように Red Hat Single Sign-On を設定するには、以下のアクションを実行します。

オペレーションモードの選択および共有データベースの設定については、本ガイドで前述しています。この章では、ロードバランサーの設定、プライベートネットワークの提供、およびクラスター内のホストの起動について説明します。

注記

IP マルチキャストなしで Red Hat Single Sign-On をクラスター化できますが、本トピックでは本ガイドの対象外となります。詳細は、JBoss EAP『設定ガイド』「JGroups」の章を参照してください。

9.2. クラスタリングの例

Red Hat Single Sign-On には、すぐに使用可能なドメインモードを活用するクラスタリングデモが同梱されています。詳細は、「Clustered Domain Example」の章を参照してください。

9.3. ロードバランサーまたはプロキシーの設定

このセクションでは、クラスター化された Red Hat Single Sign-On デプロイメントの前にリバースプロキシーまたはロードバランサーを配置する前に設定する必要があるいくつかの点について説明します。また、クラスター化されたドメインの例 であった組み込みロードバランサーの設定についても説明します。

以下の図は、ロードバランサーの使用を示しています。この例では、ロードバランサーは 3 つのクライアントと 3 つの Red Hat Single Sign-On サーバーのクラスターとの間のリバースプロキシーとして機能します。

ロードバランサーダイアグラムの例

load balancer

9.3.1. クライアント IP アドレスの特定

Red Hat Single Sign-On のいくつかの機能は、認証サーバーに接続する HTTP クライアントのリモートアドレスがクライアントマシンの実際の IP アドレスであるというファクトに依存します。以下のようになります。

  • イベントログ - 失敗したログイン試行が誤ったソース IP アドレスでログに記録される
  • SSL 必須: SSL が外部 (デフォルト) に設定されている場合、外部リクエストすべてに SSL が必要になります。
  • 認証フロー: IP アドレスを使用して外部リクエストにのみ OTP を示すカスタム認証フロー
  • 動的クライアント登録

これは、Red Hat Single Sign-On 認証サーバーの前にリバースプロキシーまたはロードバランサーがある場合に問題が発生することがあります。通常の設定とは、プライベートネットワークにあるバックエンドの Red Hat Single Sign-On サーバーインスタンスに負荷を分散し、要求を転送するパブリックネットワークにフロントエンドプロキシーがあることです。この場合、実際のクライアントの IP アドレスが Red Hat Single Sign-On サーバーインスタンスへ転送され、処理されるようにするため、いくつかの追加設定が必要です。具体的には以下を実行します。

  • HTTP ヘッダーの X-Forwarded-For および X-Forwarded-Proto を適切に設定するように、リバースプロキシーまたはロードバランサーを設定します。
  • 元の 'Host' HTTP ヘッダーを保持するようにリバースプロキシーまたはロードバランサーを設定します。
  • クライアントの IP アドレスを X-Forwarded-For ヘッダーから読み取る認証サーバーを設定します。

HTTP ヘッダーの X-Forwarded-For および X-Forwarded-Proto を生成し、元の Host HTTP ヘッダーを保持するようにプロキシーを設定することは本ガイドの対象外となります。X-Forwarded-For ヘッダーがプロキシーによって設定されていることを確認します。プロキシーが正しく設定されていないと、不正な クライアントはこのヘッダー自体を設定し、Red Hat Single Sign-On に、クライアントが実際とは異なる IP アドレスから接続していると思わせることができます。IP アドレスのブラックリストまたはホワイト一覧を実行する場合は、このことが重要になります。

プロキシー自体以外では、Red Hat Single Sign-On で設定する必要があるいくつかの点があります。プロキシーが HTTP プロトコル経由で要求を転送している場合は、ネットワークパケットからではなく、X-Forwarded-For ヘッダーからクライアントの IP アドレスをプルするように Red Hat Single Sign-On を設定する必要があります。これを行うには、プロファイル設定ファイル (操作モード に応じて standalone.xmlstandalone-ha.xml、または domain.xml) を開き、urn:jboss:domain:undertow:12.0 XML ブロックを探します。

HTTP 設定 X-Forwarded-For

<subsystem xmlns="urn:jboss:domain:undertow:12.0">
   <buffer-cache name="default"/>
   <server name="default-server">
      <ajp-listener name="ajp" socket-binding="ajp"/>
      <http-listener name="default" socket-binding="http" redirect-socket="https"
          proxy-address-forwarding="true"/>
      ...
   </server>
   ...
</subsystem>

proxy-address-forwarding 属性を http-listener 要素に追加します。この値は true に設定します。

プロキシーが HTTP ではなく AJP プロトコルを使用してリクエストを転送する場合 (Apache HTTPD + mod-cluster など)、何も異なる方法を設定する必要があります。http-listener を変更する代わりに、フィルターを追加して AJP パケットからこの情報をプルする必要があります。

AJP 設定 X-Forwarded-For

<subsystem xmlns="urn:jboss:domain:undertow:12.0">
     <buffer-cache name="default"/>
     <server name="default-server">
         <ajp-listener name="ajp" socket-binding="ajp"/>
         <http-listener name="default" socket-binding="http" redirect-socket="https"/>
         <host name="default-host" alias="localhost">
             ...
             <filter-ref name="proxy-peer"/>
         </host>
     </server>
        ...
     <filters>
         ...
         <filter name="proxy-peer"
                 class-name="io.undertow.server.handlers.ProxyPeerAddressHandler"
                 module="io.undertow.core" />
     </filters>
 </subsystem>

9.3.2. リバースプロキシーによる HTTPS/SSL の有効化

リバースプロキシーが SSL にポート 8443 を使用しない場合は、HTTPS トラフィックのリダイレクト先となるポートを設定する必要があります。

<subsystem xmlns="urn:jboss:domain:undertow:12.0">
    ...
    <http-listener name="default" socket-binding="http"
        proxy-address-forwarding="true" redirect-socket="proxy-https"/>
    ...
</subsystem>

手順

  1. http-listener 要素に redirect-socket 属性を追加します。この値は、定義する必要のあるソケットバインディングを参照する proxy-https である必要があります。
  2. 新しい socket-binding 要素を socket-binding-group 要素に追加します。

    <socket-binding-group name="standard-sockets" default-interface="public"
        port-offset="${jboss.socket.binding.port-offset:0}">
        ...
        <socket-binding name="proxy-https" port="443"/>
        ...
    </socket-binding-group>

9.3.3. 設定の確認

リバースプロキシーまたはロードバランサーの設定を確認できます

手順

  1. リバースプロキシーを介してパス /auth/realms/master/.well-known/openid-configuration を開きます。

    たとえば、リバースプロキシーアドレスが https://acme.com/ の場合は、URL https://acme.com/auth/realms/master/.well-known/openid-configuration を開きます。これにより、JSON ドキュメントに Red Hat Single Sign-On の多数のエンドポイントがリストされます。

  2. エンドポイントがリバースプロキシーまたはロードバランサーのアドレス (スキーム、ドメイン、ポート) で始まることを確認します。これを実行することで、Red Hat Single Sign-On が正しいエンドポイントを使用していることを確認します。
  3. Red Hat Single Sign-On が要求の正しいソース IP アドレスを確認することを確認する必要があります。

    これを確認するには、無効なユーザー名とパスワードを使用して管理コンソールにログインします。これにより、以下のような警告がサーバーログに記録されます。

    08:14:21,287 WARN  XNIO-1 task-45 [org.keycloak.events] type=LOGIN_ERROR, realmId=master, clientId=security-admin-console, userId=8f20d7ba-4974-4811-a695-242c8fbd1bf8, ipAddress=X.X.X.X, error=invalid_user_credentials, auth_method=openid-connect, auth_type=code, redirect_uri=http://localhost:8080/auth/admin/master/console/?redirect_fragment=%2Frealms%2Fmaster%2Fevents-settings, code_id=a3d48b67-a439-4546-b992-e93311d6493e, username=admin
  4. ipAddress の値が、リバースプロキシーまたはロードバランサーの IP アドレスではなく、ログインを試みたマシンの IP アドレスであることを確認します。

9.3.4. 組み込みロードバランサーの使用

このセクションでは、「クラスター化ドメインの例」で説明されている組み込みロードバランサーの設定を説明します。

「クラスター化されたドメインの例」 は、1 台のマシンでのみ実行されるように設計されています。別のホストでスレーブを起動するには、

  1. domain.xml ファイルを編集して、新規ホストのスレーブを指定します。
  2. サーバーのディストリビューションをコピーします。domain.xml ファイル、host.xml ファイル、または host-master.xml ファイルは必要ありません。また、standalone/ ディレクトリーも必要ありません。
  3. host-slave.xml ファイルを編集して、コマンドラインで使用するバインドアドレスを変更するか、または上書きします。

手順

  1. domain.xml を開いて、新しいホストスレーブをロードバランサー設定に登録できるようにします。
  2. load-balancer プロファイルの undertow 設定に移動します。reverse-proxy XML ブロック内に remote-host3 という名前の新規 host 定義を追加します。

    domain.xml reverse-proxy config

    <subsystem xmlns="urn:jboss:domain:undertow:12.0">
      ...
      <handlers>
          <reverse-proxy name="lb-handler">
             <host name="host1" outbound-socket-binding="remote-host1" scheme="ajp" path="/" instance-id="myroute1"/>
             <host name="host2" outbound-socket-binding="remote-host2" scheme="ajp" path="/" instance-id="myroute2"/>
             <host name="remote-host3" outbound-socket-binding="remote-host3" scheme="ajp" path="/" instance-id="myroute3"/>
          </reverse-proxy>
      </handlers>
      ...
    </subsystem>

    output-socket-binding は、domain.xml ファイルの後半に設定された socket-binding を示す論理名です。instance-id 属性は、負荷分散時にスティッキーセッションを有効にするために cookie によってこの値が使用されるため、新規ホストに一意である必要があります。

  3. load-balancer-sockets socket-binding-group に移動し、remote-host3outbound-socket-binding を追加します。

    この新しいバインディングは新規ホストのホストおよびポートを参照する必要があります。

    domain.xml outbound-socket-binding

    <socket-binding-group name="load-balancer-sockets" default-interface="public">
        ...
        <outbound-socket-binding name="remote-host1">
            <remote-destination host="localhost" port="8159"/>
        </outbound-socket-binding>
        <outbound-socket-binding name="remote-host2">
            <remote-destination host="localhost" port="8259"/>
        </outbound-socket-binding>
        <outbound-socket-binding name="remote-host3">
            <remote-destination host="192.168.0.5" port="8259"/>
        </outbound-socket-binding>
    </socket-binding-group>

9.3.4.1. マスターバインドアドレス

次に、マスターホストの public および management バインドアドレスを変更する必要があります。バインドアドレス の章で説明されているように domain.xml ファイルを編集するか、以下のようにコマンドラインでこれらのバインドアドレスを指定します。

$ domain.sh --host-config=host-master.xml -Djboss.bind.address=192.168.0.2 -Djboss.bind.address.management=192.168.0.2

9.3.4.2. ホストスレーブバインドアドレス

次に、publicmanagement、およびドメインコントローラーのバインドアドレス (jboss.domain.master-address) を変更する必要があります。host-slave.xml ファイルを編集するか、以下のようにコマンドラインで指定します。

$ domain.sh --host-config=host-slave.xml
     -Djboss.bind.address=192.168.0.5
      -Djboss.bind.address.management=192.168.0.5
       -Djboss.domain.master.address=192.168.0.2

ホストのスレーブの IP アドレスに関連する jboss.bind.address 値および jboss.bind.address.management の値です。jboss.domain.master.address の値は、マスターホストの管理アドレスであるドメインコントローラーの IP アドレスである必要があります。

関連情報

  • 他のソフトウェアベースのロードバランサーの使用方法は、JBoss EAP『設定ガイド』「負荷分散」を参照してください。

9.4. スティッキーセッション

通常のクラスターデプロイメントは、プライベートネットワークにあるロードバランサー (逆引きプロキシー) および 2 つ以上の Red Hat Single Sign-On サーバーで構成されます。パフォーマンスの目的で、ロードバランサーが特定のブラウザーセッションに関連するすべてのリクエストを同じ Red Hat Single Sign-On バックエンドノードに転送する場合に便利です。

Red Hat Single Sign-On は、現在の認証セッションとユーザーセッションに関連するデータを保存するために、Red Hat Single Sign-On が Infinispan の分散キャッシュを使用していることです。Infinispan の分散キャッシュは、デフォルトで 1 所有者で設定されます。つまり、特定のセッションは 1 つのクラスターノードにのみ保存され、他のノードはそれにアクセスする場合はリモートでセッションを検索する必要があります。

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

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

  • ユーザーが最初のリクエストを送信して、Red Hat Single Sign-On のログイン画面を表示する
  • この要求はフロントエンドロードバランサーにより提供されます。このロードバランサーは、これをランダムなノード (例: node1) に転送します。厳密に言及されているので、ノードはランダムにする必要はありませんが、他の基準 (クライアント IP アドレスなど) に従って選択できます。これらはすべて、基盤のロードバランサーの実装および設定 (逆引きプロキシー) によって異なります。
  • Red Hat Single Sign-On は、ランダム ID (例: 123) で認証セッションを作成し、Infinispan キャッシュに保存します。
  • Infinispan の分散キャッシュは、セッション ID のハッシュに基づいてセッションのプライマリー所有者を割り当てます。詳細は Infinispan のドキュメント を参照してください。Infinispan が、node2 をこのセッションの所有者として割り当てたとしましょう。
  • Red Hat Single Sign-On は、<session-id>.<owner-node-id> のような形式で cookie AUTH_SESSION_ID を作成します。この例では、123.node2 になります。
  • ブラウザーで Red Hat Single Sign-On ログイン画面と AUTH_SESSION_ID クッキーを持つユーザーに対して応答が返されます。

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

クラスターの設定にスティッキーセッションは必須ではありませんが、上記の理由でパフォーマンスが適しています。AUTH_SESSION_ID cookie をスティッキーするようにロードバランサーを設定する必要があります。これは、ロードバランサーによって異なります。

起動時にシステムプロパティー jboss.node.name を使用するには、Red Hat Single Sign-On で、ルートの名前に対応する値を使用することが推奨されます。たとえば、-Djboss.node.name=node1 は、node1 を使用してルートを特定します。このルートは Infinispan キャッシュによって使用され、ノードが特定のキーの所有者である場合に AUTH_SESSION_ID クッキーに割り当てられます。このシステムプロパティーを使用した起動コマンドの例を以下に示します。

cd $RHSSO_NODE1
./standalone.sh -c standalone-ha.xml -Djboss.socket.binding.port-offset=100 -Djboss.node.name=node1

実稼働環境では、ルート名はバックエンドホストと同じ名前を使用する必要がありますが、必須ではありません。別のルート名を使用できます。たとえば、プライベートネットワーク内で Red Hat Single Sign-On サーバーのホスト名を非表示にする場合などです。

9.4.1. ルートの追加を無効化

一部のロードバランサーは、バックエンド Red Hat Single Sign-On ノードに依存する代わりに、ルート情報を追加するように設定できます。ただし、上記で説明されているように、Red Hat Single Sign-On によるルートの追加が推奨されます。Red Hat Single Sign-On は特定のセッションの所有者で、そのノード (必ずしもローカルノードではない) にルーティングできるエンティティーを認識するため、この方法によりパフォーマンスが向上します。

以下を Red Hat Single Sign-On サブシステム設定の RHSSO_HOME/standalone/configuration/standalone-ha.xml ファイルに追加すると、Red Hat Single Sign-On による AUTH_SESSION_ID cookie へのルート情報の追加を無効にできます。

<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
  ...
    <spi name="stickySessionEncoder">
        <provider name="infinispan" enabled="true">
            <properties>
                <property name="shouldAttachRoute" value="false"/>
            </properties>
        </provider>
    </spi>

</subsystem>

9.5. マルチキャストネットワークの設定

デフォルトのクラスタリングサポートには、IP マルチキャストが必要です。マルチキャストはネットワークブロードキャストプロトコルです。このプロトコルは、起動時にクラスターを検出し、参加するために使用されます。また、Red Hat Single Sign-On が使用する分散キャッシュのレプリケーションおよび無効化のメッセージをブロードキャストするために使用されます。

Red Hat Single Sign-On のクラスタリングサブシステムは、JGroups スタックで実行されます。クラスタリングのバインドアドレスは、デフォルトの IP アドレスとして 127.0.0.1 を使用して、プライベートネットワークインターフェースにすぐにバインドされます。

手順

  1. バインドアドレス の章で説明されている standalone-ha.xml セクションまたは domain.xml セクションを編集します。

    プライベートネットワークの設定

        <interfaces>
            ...
            <interface name="private">
                <inet-address value="${jboss.bind.address.private:127.0.0.1}"/>
            </interface>
        </interfaces>
        <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
            ...
            <socket-binding name="jgroups-mping" interface="private" port="0" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45700"/>
            <socket-binding name="jgroups-tcp" interface="private" port="7600"/>
            <socket-binding name="jgroups-tcp-fd" interface="private" port="57600"/>
            <socket-binding name="jgroups-udp" interface="private" port="55200" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45688"/>
            <socket-binding name="jgroups-udp-fd" interface="private" port="54200"/>
            <socket-binding name="modcluster" port="0" multicast-address="224.0.1.105" multicast-port="23364"/>
            ...
        </socket-binding-group>

  2. jboss.bind.address.private および jboss.default.multicast.address と、クラスタリングスタックのサービスのポートを設定します。

    注記

    IP マルチキャストなしで Red Hat Single Sign-On をクラスター化できますが、本トピックでは本ガイドの対象外となります。詳細は、JBoss EAP『設定ガイド』「JGroups」を参照してください。

9.6. 安全なクラスター通信

クラスターノードがプライベートネットワーク上に分離されている場合は、プライベートネットワークにアクセスしたり、クラスター内の通信を表示できるようにする必要があります。さらに、クラスター通信の認証および暗号化を有効にすることもできます。プライベートネットワークがセキュアである限り、認証および暗号化を有効にする必要はありません。Red Hat Single Sign-On は、いずれの場合でもクラスターに非常に機密情報を送信しません。

クラスタリング通信の認証および暗号化を有効にする場合は、JBoss EAP『設定ガイド』「クラスターのセキュア化」を参照してください。

9.7. シリアル化されたクラスターの起動

Red Hat Single Sign-On クラスターノードは、同時に起動することができます。Red Hat Single Sign-On サーバーインスタンスが起動すると、データベースの移行、インポート、または初回の初期化が行われる場合があります。DB ロックは、クラスターノードが同時に起動する場合に、起動アクションが相互に競合しないようにするために使用されます。

デフォルトでは、このロックの最大タイムアウトは 900 秒です。ノードがタイムアウトを超えてこのロックで待機している場合、ノードは起動に失敗します。通常、デフォルト値を増減する必要はありませんが、ディストリビューションの standalone.xml ファイル、standalone-ha.xml ファイル、または domain.xml ファイルで設定できます。このファイルの場所は、操作モード によって異なります。

<spi name="dblock">
    <provider name="jpa" enabled="true">
        <properties>
            <property name="lockWaitTimeout" value="900"/>
        </properties>
    </provider>
</spi>

9.8. クラスターのブート

クラスターでの Red Hat Single Sign-On の起動は、操作モード によって異なります。

スタンドアロンモード

$ bin/standalone.sh --server-config=standalone-ha.xml

ドメインモード

$ bin/domain.sh --host-config=host-master.xml
$ bin/domain.sh --host-config=host-slave.xml

追加のパラメーターまたはシステムプロパティーを使用する必要がある場合があります。たとえば、「スティッキーセッション」のセクションで説明されているように、バインディングホストまたはシステムプロパティー jboss.node.name パラメーターでルートの名前を指定するためのパラメーター -b です。

9.9. トラブルシューティング

  • クラスターの実行時に、両方のクラスターノードのログに以下のようなメッセージが表示されることに注意してください。

    INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (Incoming-10,shared=udp)
    ISPN000094: Received new cluster view: [node1/keycloak|1] (2) [node1/keycloak, node2/keycloak]

    上記のノードが 1 つのみであれば、クラスターホストが結合していない可能性があります。

    通常、これらの通信にファイアウォールなしでクラスターノードをプライベートネットワークに配置することがベストプラクティスになります。ファイアウォールは、お使いのネットワークへのパブリックアクセスポイントでのみ有効にできます。何らかの理由でクラスターノードでファイアウォールを有効にしておく必要がある場合は、一部のポートを開く必要があります。デフォルト値は UDP ポート 55200 で、マルチキャストポート 45688 とマルチキャストアドレス 230.0.0.4 です。JGroups スタックの診断などの追加機能を有効にする場合は、より多くのポートを開放する必要があることに注意してください。Red Hat Single Sign-On は、クラスタリングの大半を Infinispan/JGroups に委任します。詳細は、JBoss EAP『設定ガイド』「JGroups」を参照してください。

  • フェイルオーバーのサポート (高可用性)、エビクション、有効期限、およびキャッシュの調整を検討する場合は、10章サーバーキャッシュ設定 を参照してください。

第10章 サーバーキャッシュ設定

Red Hat Single Sign-On には、2 種類のキャッシュがあります。DB の負荷を減らして、データをメモリーに維持することで、データベースの前にあるキャッシュのタイプが 1 つあり、全体的に応答時間を削減します。レルム、クライアント、ロール、およびユーザーメタデータはこの種類のキャッシュに保存されます。このキャッシュはローカルキャッシュです。より Red Hat Single Sign-On サーバーがあるクラスター内にある場合でも、ローカルキャッシュはレプリケーションを使用しません。代わりに、ローカルにコピーのみを保持し、エントリーが更新されても無効化メッセージが残りのクラスターに送信され、エントリーはエビクトされます。別個のレプリケートされたキャッシュ work があります。この作業では、ローカルキャッシュから削除されるエントリーについて、無効化メッセージをクラスター全体に送信します。これにより、ネットワークトラフィックが大幅に削減され、効率的な状態になり、機密メタデータをネットワーク経由で送信しないようにします。

2 つ目のキャッシュは、ユーザーセッション、オフライントークンの管理、およびログイン失敗の追跡を処理し、サーバーがパスワードのシャッシングやその他の攻撃を検出できるようにします。これらのキャッシュに保持されるデータは一時的なものですが、メモリーのみはクラスター全体に複製される可能性があります。

本章では、クラスター化されたデプロイメントと非クラスターデプロイメント向けのこれらのキャッシュの設定オプションについて説明します。

注記

これらのキャッシュの高度な設定については、JBoss EAP『設定ガイド』「Infinispan」セクションを参照してください。

10.1. エビクションと有効期限

Red Hat Single Sign-On には複数の異なるキャッシュが設定されます。セキュアなアプリケーション、一般的なセキュリティーデータ、設定オプションに関する情報を保持するレルムキャッシュがあります。また、ユーザーメタデータを含むユーザーキャッシュもあります。両方のキャッシュを 10000 エントリーに制限し、最も最近使用されたエビクションストラテジーを使用します。それぞれがクラスター設定のエビクションを制御するオブジェクトリビジョンキャッシュにも関連付けられます。このキャッシュは暗黙的に作成され、設定されたサイズの 2 倍になります。認証データを保持する authorization キャッシュにも同様のが適用されます。keys キャッシュは外部キーについてのデータを保持し、専用のリビジョンキャッシュを持つ必要はありません。むしろ、有効期限 が明示的に宣言されているため、キーは定期的に期限切れになり、外部クライアントまたは ID プロバイダーから定期的にダウンロードされます。

これらのキャッシュのエビクションポリシーおよび最大エントリーは、操作モード に応じて、standalone.xmlstandalone-ha.xml、または domain.xml で設定できます。設定ファイルには、以下のような infinispan サブシステムの一部があります。

<subsystem xmlns="urn:jboss:domain:infinispan:12.0">
    <cache-container name="keycloak">
        <local-cache name="realms">
            <object-memory size="10000"/>
        </local-cache>
        <local-cache name="users">
            <object-memory size="10000"/>
        </local-cache>
        ...
        <local-cache name="keys">
            <object-memory size="1000"/>
            <expiration max-idle="3600000"/>
        </local-cache>
        ...
    </cache-container>

許可されるエントリーの数を制限するか、拡張するには、object 要素または特定のキャッシュ設定の expiration 要素を追加または編集します。

さらに、個別のキャッシュ sessionsclientSessionsofflineSessionsofflineClientSessionsloginFailures、および actionTokens もあります。これらのキャッシュはクラスター環境で配布され、デフォルトでバインドされないサイズに設定されます。バインドされている場合、一部のセッションが失われる可能性があります。期限切れのセッションは、制限なしでこれらのキャッシュのサイズを増やしないように、Red Hat Single Sign-On が内部でクリアされます。多数のセッションが原因でメモリーの問題が発生する場合は、以下を試行できます。

  • クラスターのサイズを増やします (より多くのノードは、セッションがノード間で均等に分散されることを意味します)
  • Red Hat Single Sign-On サーバープロセスのメモリーを増やす。
  • 所有者の数を減らし、1 箇所にキャッシュが 1 度保存されるようにします。詳細は、「レプリケーションおよびフェイルオーバー」 を参照してください。
  • 分散キャッシュの L1 ライフスパンを無効にします。詳細は、Infinispan ドキュメントを参照してください。
  • セッションのタイムアウトを減らします。これは、Red Hat Single Sign-On の管理コンソールの各レルムに個別に実行できます。ただし、エンドユーザーのユーザビリティーに影響する可能性があります。詳細は、「 タイム アウト」を参照してください。

他にもレプリケートされたキャッシュ (work) があり、大半はクラスターノード間でメッセージを送信するために使用されます。また、デフォルトではバインドされません。ただし、このキャッシュのエントリーは非常に短くなるため、このキャッシュでメモリーの問題は発生しません。

10.2. レプリケーションおよびフェイルオーバー

sessionsauthenticationSessionsofflineSessionsloginFailures などのキャッシュがあります (詳細は 「エビクションと有効期限」 を参照)。これらは、クラスター化されたセットアップを使用する場合に分散キャッシュとして設定されます。エントリーは、すべての単一ノードに複製されませんが、代わりに 1 つ以上のノードがそのデータの所有者として選択されます。ノードが特定のキャッシュエントリーの所有者ではない場合、そのノードはクラスターに対してクエリーを実行し、これを取得します。フェイルオーバーの意味は、一部のデータを所有するすべてのノードがダウンした場合に、そのデータは永久に失われることを意味します。デフォルトでは、Red Hat Single Sign-On は、データの所有者を 1 つだけ指定します。したがって、1 つのノードがそのデータを失う場合。これは通常、ユーザーをログアウトし、再度ログインする必要があることを意味します。

distributed-cache 宣言の owners 属性を変更すると、データを複製するノード数を変更できます。

owners

<subsystem xmlns="urn:jboss:domain:infinispan:12.0">
   <cache-container name="keycloak">
       <distributed-cache name="sessions" owners="2"/>
...

ここでは、少なくとも 2 つのノードが 1 つの特定ユーザーログインセッションを複製するように変更されました。

ヒント

推奨される所有者の数は、実際のデプロイメントによって異なります。ノードがダウンしたときにユーザーがログアウトしても問題がない場合は、所有者が十分であるため、レプリケーションは回避できます。

ヒント

通常、スティッキーセッションでロードバランサーを使用するように環境を設定します。特定の要求が提供される Red Hat Single Sign-On サーバーのパフォーマンスには、通常分散キャッシュからのデータの所有者であるため、データをローカルで検索できます。詳細は、「スティッキーセッション」 を参照してください。

10.3. キャッシュの無効化

レルムまたはユーザーキャッシュを無効にできます。

手順

  1. ディストリビューションの standalone.xml ファイル、standalone-ha.xml ファイル、または domain.xml ファイルを編集します。

    このファイルの場所は、操作モード によって異なります。これが設定ファイルのサンプルです。

        <spi name="userCache">
            <provider name="default" enabled="true"/>
        </spi>
    
        <spi name="realmCache">
            <provider name="default" enabled="true"/>
        </spi>
  2. 無効にするキャッシュの enabled 属性を false に設定します。
  3. この変更を有効にするには、サーバーを再起動してください。

10.4. ランタイム時のキャッシュの消去

レルムキャッシュ、ユーザーキャッシュ、または外部公開鍵を消去できます。

手順

  1. 管理コンソールにログインします。
  2. Realm Settings をクリックします。
  3. Cache タブをクリックします。
  4. レルムキャッシュ、ユーザーキャッシュ、または外部公開鍵のキャッシュを消去します。
注記

すべてのレルムに対してキャッシュが消去されます!

第11章 Red Hat Single Sign-On Operator

Red Hat Single Sign-On Operator は、OpenShift での Red Hat Single Sign-On の管理を自動化します。この Operator を使用して、管理タスクを自動化するカスタムリソース (CR) を作成します。たとえば、Red Hat Single Sign-On 管理コンソールでクライアントまたはユーザーを作成する代わりに、カスタムリソースを作成して、これらのタスクを実行することができます。カスタムリソースは、管理タスクのパラメーターを定義する YAML ファイルです。

カスタムリソースを作成して、以下のタスクを実行できます。

注記

レルム、クライアント、およびユーザーにカスタムリソースを作成したら、Red Hat Single Sign-On 管理コンソールを使用するか、oc コマンドを使用したカスタムリソースとして管理できます。ただし、Operator は変更するカスタムリソースに対して 1 つの方法を同期するため、両方の方法を使用することはできません。たとえば、レルムカスタムリソースを変更すると、管理コンソールで変更が表示されます。ただし、管理コンソールを使用してレルムを変更する場合、これらの変更はカスタムリソースには影響を与えません。

クラスターへの Red Hat Single Sign-On Operator のインストールによる Operator の使用を開始します。

11.1. クラスターへの Red Hat Single Sign-On Operator のインストール

Red Hat Single Sign-On Operator をインストールするには、以下を使用できます。

11.1.1. Operator Lifecycle Manager を使用したインストール

前提条件

  • cluster-admin パーミッション、または管理者によって付与される同等のレベルのパーミッションがある。

手順

OpenShift クラスターで以下の手順を実行します。

  1. OpenShift Container Platform Web コンソールを開きます。
  2. 左側の列で、Operators, OperatorHub をクリックします。
  3. Red Hat Single Sign-On Operator を検索します。

    OpenShift の OperatorHub タブ

    operator openshift operatorhub

  4. Red Hat Single Sign-On Operator アイコンをクリックします。

    Install ページが開きます。

    OpenShift への Operator Install ページ

    operator olm installation

  5. Install をクリックします。
  6. namespace を選択し、Subscribe をクリックします。

    OpenShift での namespace 選択

    installed namespace

    Operator はインストールを開始します。

関連資料

11.2. 異なる RH-SSO バージョンとの Operator の互換性

RH-SSO Operator 7.6 は、RH-SSO 7.5 と完全に互換性があります。デフォルトで 7.6 Operator は RH-SSO 7.6 をデプロイします。代わりに RH-SSO 7.5 イメージを使用するには、Operator Pod で RELATED_IMAGE_RHSSO 環境変数を設定してイメージの座標を上書きします。これを変更するには、OpenShift クラスター内で RH-SSO Operator の OLM サブスクリプション を更新します。以下に例を示します。

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
spec:
  channel: stable
  config:
    env:
      - name: RELATED_IMAGE_RHSSO
        value: 'registry.redhat.io/rh-sso-7/sso75-openshift-rhel8:7.5'
  name: rhsso-operator
  source: redhat-operators
  sourceNamespace: openshift-marketplace
  ...

RH-SSO 7.5 での RH-SSO Operator 7.6 の使用は完全にサポートされています。

関連情報

11.3. 実稼働環境での Red Hat Single Sign-On Operator の使用

  • 組み込み DB の使用は、実稼働環境ではサポートされていません。
  • バックアップ CRD は非推奨であり、実稼働環境ではサポートされていません。
  • Keycloak CR の podDisruptionBudget フィールドは非推奨となり、Operator が Kubernetes バージョン 1.25 以降にデプロイされる際に無視されます。
  • それ以外の CRD については、v1alpha1 バージョンにかかわらず本番環境で完全にサポートされています。この CRD バージョンで重大な変更を加える予定はありません。

11.4. カスタムリソースを使用した Red Hat Single Sign-On のインストール

Operator を使用して Keycloak カスタムリソースを作成して、Red Hat Single Sign-On のインストールを自動化できます。カスタムリソースを使用して Red Hat Single Sign-On をインストールする際に、ここに説明されているコンポーネントおよびサービスを作成し、続いて表示されるグラフで示唆します。

  • keycloak-db-secret - データベースのユーザー名、パスワード、および外部アドレスなどのプロパティーを保存します (外部データベースに接続する場合)。
  • credentials-<CR-Name> - Red Hat Single Sign-On 管理コンソールにログインする管理者のユーザー名とパスワードです (<CR-Name>Keycloak カスタムリソース名に基づいています)。
  • keycloak - 高可用性サポートのある StatefulSet として実装される Keycloak デプロイメント仕様
  • keycloak-postgresql - PostgreSQL データベースインストールを開始します。
  • keycloak-discovery サービス - JDBC_PING 検出を実行します。
  • keycloak サービス - HTTPS 経由で Red Hat Single Sign-On への接続 (HTTP はサポートされていません)
  • keycloak-postgresql サービス - 内部および外部 (使用されている場合) のデータベースインスタンスを接続します。
  • keycloak ルート - OpenShift から Red Hat Single Sign-On 管理コンソールにアクセスするための URL

Operator コンポーネントおよびサービスがどのように対話するか

operator components

11.4.1. Keycloak カスタムリソース

Keycloak カスタムリソースは、インストールのパラメーターを定義する YAML ファイルです。このファイルには、3 つのプロパティーが含まれます。

  • instances - 高可用性モードで実行中のインスタンス数を制御します。
  • externalAccess - enabledTrue の場合、Operator は Red Hat Single Sign-On クラスターの OpenShift のルートを作成します。Route に自動選択される ホスト 名を上書きするように host を設定できます。
  • externalDatabase - 外部でホストされているデータベースに接続するため。このトピックは、本ガイドの 外部データベース のセクションで説明しています。false に設定すると、テスト目的でのみ使用され、組み込み PostgreSQL データベースがインストールされます。externalDatabase:false は実稼働環境ではサポートされていないことに注意してください。

Keycloak カスタムリソースの YAML ファイルのサンプル

apiVersion: keycloak.org/v1alpha1
kind: Keycloak
metadata:
  name: example-sso
  labels:
    app: sso
spec:
  instances: 1
  externalAccess:
    enabled: True

注記

YAML ファイルを更新しても、Red Hat Single Sign-On 管理コンソールに表示される変更は更新できますが、管理コンソールへの変更はカスタムリソースを更新しません。

11.4.2. OpenShift での Keycloak カスタムリソースの作成

OpenShift では、カスタムリソースを使用して管理コンソールの URL であるルートを作成し、管理コンソールのユーザー名とパスワードを保持するシークレットを検索します。

前提条件

  • このカスタムリソースの YAML ファイルがある。
  • cluster-admin パーミッション、または管理者によって付与される同等のレベルのパーミッションがある。

手順

  1. YAML ファイルを使用してルートを作成します (oc create -f <filename>.yaml -n <namespace>)。以下は例になります。

    $ oc create -f sso.yaml -n sso
    keycloak.keycloak.org/example-sso created

    ルートは OpenShift に作成されます。

  2. OpenShift Web コンソールにログインします。
  3. NetworkingRoutes を選択し、Keycloak を検索します。

    OpenShift Web コンソールのルート画面

    route ocp

  4. Keycloak ルートのある画面で、Location の下にある URL をクリックします。

    Red Hat Single Sign-On の管理コンソールのログイン画面が表示されます。

    管理コンソールのログイン画面

    login empty

  5. OpenShift Web コンソールで管理コンソールのユーザー名およびパスワードを確認します。WorkloadsSecrets をクリックし、Keycloak を検索します。

    OpenShift Web コンソールのシークレット画面

    secrets ocp

  6. 管理コンソールのログイン画面に、ユーザー名とパスワードを入力します。

    管理コンソールのログイン画面

    login complete

    次に、Keycloak カスタムリソースによってインストールされた Red Hat Single Sign-On のインスタンスにログインしている。レルム、クライアント、およびユーザーのカスタムリソースを作成できます。

    Red Hat Single Sign-On マスターレルム

    new install cr

  7. カスタムリソースのステータスを確認します。

    $ oc describe keycloak <CR-name>

結果

Operator がカスタムリソースを処理した後に、以下のコマンドでステータスを表示します。

$ oc describe keycloak <CR-name>

Keycloak カスタムリソースのステータス

Name:         example-keycloak
Namespace:    keycloak
Labels:       app=sso
Annotations:  <none>
API Version:  keycloak.org/v1alpha1
Kind:         Keycloak
Spec:
  External Access:
    Enabled:  true
  Instances:  1
Status:
  Credential Secret:  credential-example-keycloak
  Internal URL:       https://<External URL to the deployed instance>
  Message:
  Phase:              reconciling
  Ready:              true
  Secondary Resources:
    Deployment:
      keycloak-postgresql
    Persistent Volume Claim:
      keycloak-postgresql-claim
    Prometheus Rule:
      keycloak
    Route:
      keycloak
    Secret:
      credential-example-keycloak
      keycloak-db-secret
    Service:
      keycloak-postgresql
      keycloak
      keycloak-discovery
    Service Monitor:
      keycloak
    Stateful Set:
      keycloak
  Version:
Events:

関連資料

  • Red Hat Single Sign-On のインストールが完了すると、レルムカスタムリソースを作成 する準備が整います。
  • 外部データベースはサポートされているオプションであり、Keycloak カスタムリソースで有効にする必要があります。このオプションはテストでのみ無効にし、実稼働環境に切り替えるときに有効にすることができます。「外部データベースへの接続」を参照してください。

11.5. レルムカスタムリソースの作成

Operator を使用して、カスタムリソースで定義されているように Red Hat Single Sign-On でレルムを作成できます。YAML ファイルで、レルムカスタムリソースのプロパティーを定義します。

注記

YAML ファイルを作成または削除すると、レルムの作成または削除のみが可能で、変更は Red Hat Single Sign-On 管理コンソールに表示されます。ただし、管理コンソールへの変更は反映されず、レルムの作成後に CR の更新はサポートされません。

Realm カスタムリソースの YAML ファイルの例

apiVersion: keycloak.org/v1alpha1
kind: KeycloakRealm
metadata:
  name: test
  labels:
    app: sso
spec:
  realm:
    id: "basic"
    realm: "basic"
    enabled: True
    displayName: "Basic Realm"
  instanceSelector:
    matchLabels:
      app: sso

前提条件

  • このカスタムリソースの YAML ファイルがある。
  • YAML ファイルでは、instanceSelector の下にある app が、Keycloak カスタムリソースのラベルと一致します。これらの値に一致させることで、Red Hat Single Sign-On の適切なインスタンスでレルムを作成することができます。
  • cluster-admin パーミッション、または管理者によって付与される同等のレベルのパーミッションがある。

手順

  1. このコマンドは、作成した YAML ファイルで使用します (oc create -f <realm-name>.yaml)。以下は例になります。

    $ oc create -f initial_realm.yaml
    keycloak.keycloak.org/test created
  2. Red Hat Single Sign-On の関連インスタンス向けに、管理コンソールにログインします。
  3. Select Realm をクリックし、作成したレルムを見つけます。

    新しいレルムが開きます。

    管理コンソールのマスターレルム

    test realm cr

結果

Operator がカスタムリソースを処理した後に、以下のコマンドでステータスを表示します。

$ oc describe keycloak <CR-name>

レルムカスタムリソースのステータス

Name:         example-keycloakrealm
Namespace:    keycloak
Labels:       app=sso
Annotations:  <none>
API Version:  keycloak.org/v1alpha1
Kind:         KeycloakRealm
Metadata:
  Creation Timestamp:  2019-12-03T09:46:02Z
  Finalizers:
    realm.cleanup
  Generation:        1
  Resource Version:  804596
  Self Link:         /apis/keycloak.org/v1alpha1/namespaces/keycloak/keycloakrealms/example-keycloakrealm
  UID:               b7b2f883-15b1-11ea-91e6-02cb885627a6
Spec:
  Instance Selector:
    Match Labels:
      App: sso
  Realm:
    Display Name:  Basic Realm
    Enabled:       true
    Id:            basic
    Realm:         basic
Status:
  Login URL:
  Message:
  Phase:      reconciling
  Ready:      true
Events:       <none>

関連資料

11.6. クライアントカスタムリソースの作成

Operator を使用して、カスタムリソースで定義されているように Red Hat Single Sign-On でクライアントを作成できます。レルムのプロパティーを YAML ファイルに定義します。

注記

YAML ファイルを更新しても、Red Hat Single Sign-On 管理コンソールに表示される変更は更新できますが、管理コンソールへの変更はカスタムリソースを更新しません。

クライアントカスタムリソースの YAML ファイルの例

apiVersion: keycloak.org/v1alpha1
kind: KeycloakClient
metadata:
  name: example-client
  labels:
    app: sso
spec:
  realmSelector:
     matchLabels:
      app: <matching labels for KeycloakRealm custom resource>
  client:
    # auto-generated if not supplied
    #id: 123
    clientId: client-secret
    secret: client-secret
    # ...
    # other properties of Keycloak Client

前提条件

  • このカスタムリソースの YAML ファイルがある。
  • cluster-admin パーミッション、または管理者によって付与される同等のレベルのパーミッションがある。

手順

  1. このコマンドは、作成した YAML ファイルで使用します (oc create -f <client-name>.yaml)。以下は例になります。

    $ oc create -f initial_client.yaml
    keycloak.keycloak.org/example-client created
  2. Red Hat Single Sign-On の関連インスタンス用に、Red Hat Single Sign-On 管理コンソールにログインします。
  3. Clients をクリックします。

    クライアントの一覧に新しいクライアントが表示されます。

    clients

結果

クライアントの作成後に、Operator は keycloak-client-secret-<custom resource name> という命名パターンを使用して Client ID とクライアントのシークレットが含まれる Secret を作成します。以下に例を示します。

クライアントのシークレット

apiVersion: v1
data:
  CLIENT_ID: <base64 encoded Client ID>
  CLIENT_SECRET: <base64 encoded Client Secret>
kind: Secret

Operator がカスタムリソースを処理した後に、以下のコマンドでステータスを表示します。

$ oc describe keycloak <CR-name>

クライアントのカスタムリソースのステータス

Name:         client-secret
Namespace:    keycloak
Labels:       app=sso
API Version:  keycloak.org/v1alpha1
Kind:         KeycloakClient
Spec:
  Client:
    Client Authenticator Type:     client-secret
    Client Id:                     client-secret
    Id:                            keycloak-client-secret
  Realm Selector:
    Match Labels:
      App:  sso
Status:
  Message:
  Phase:    reconciling
  Ready:    true
  Secondary Resources:
    Secret:
      keycloak-client-secret-client-secret
Events:  <none>

関連資料

11.7. ユーザーカスタムリソースの作成

Operator を使用して、カスタムリソースで定義されているように Red Hat Single Sign-On でユーザーを作成できます。YAML ファイルで、ユーザーカスタムリソースのプロパティーを定義します。

注記

YAML ファイルのパスワードを除き、プロパティーを更新でき、変更は Red Hat Single Sign-On 管理コンソールに表示されますが、管理コンソールへの変更はカスタムリソースを更新しません。

ユーザーカスタムリソースのサンプル YAML ファイル

apiVersion: keycloak.org/v1alpha1
kind: KeycloakUser
metadata:
  name: example-user
spec:
  user:
    username: "realm_user"
    firstName: "John"
    lastName: "Doe"
    email: "user@example.com"
    enabled: True
    emailVerified: False
    credentials:
      - type: "password"
        value: "12345"
    realmRoles:
      - "offline_access"
    clientRoles:
      account:
        - "manage-account"
      realm-management:
        - "manage-users"
  realmSelector:
    matchLabels:
      app: sso

前提条件

  • このカスタムリソースの YAML ファイルがある。
  • realmSelector は、既存のレルムカスタムリソースのラベルに一致する。
  • cluster-admin パーミッション、または管理者によって付与される同等のレベルのパーミッションがある。

手順

  1. このコマンドは作成した YAML ファイルで使用します (oc create -f <user_cr>.yaml)。以下は例になります。

    $ oc create -f initial_user.yaml
    keycloak.keycloak.org/example-user created
  2. Red Hat Single Sign-On の関連インスタンス向けに、管理コンソールにログインします。
  3. Users をクリックします。
  4. YAML ファイルで定義したユーザーを検索します。

    ユーザーを検索するには、別のレルムに切り替える必要がある場合があります。

    realm user

結果

ユーザーの作成後、Operator は credential-<realm name>-<username>-<namespace> という命名パターンを使用してシークレットを作成します。このシークレットには、ユーザー名と、CR credentials 属性で指定されている場合はパスワードが含まれます。

以下に例を示します。

KeycloakUser シークレット

kind: Secret
apiVersion: v1
data:
  password: <base64 encoded password>
  username: <base64 encoded username>
type: Opaque

Operator がカスタムリソースを処理した後に、以下のコマンドでステータスを表示します。

$ oc describe keycloak <CR-name>

ユーザーカスタムリソースのステータス

Name:         example-realm-user
Namespace:    keycloak
Labels:       app=sso
API Version:  keycloak.org/v1alpha1
Kind:         KeycloakUser
Spec:
  Realm Selector:
    Match Labels:
      App: sso
  User:
    Email:           realm_user@redhat.com
    Credentials:
      Type:          password
      Value:         <user password>
    Email Verified:  false
    Enabled:         true
    First Name:      John
    Last Name:       Doe
    Username:        realm_user
Status:
  Message:
  Phase:    reconciled
Events:     <none>

関連資料

11.8. 外部データベースへの接続

Operator を使用して、keycloak-db-secret YAML ファイルを作成し、Keycloak CR externalDatabase プロパティーを有効に設定することで、外部 PostgreSQL データベースに接続できます。値は Base64 でエンコードされていることに注意してください。

keycloak-db-secretの YAML ファイルサンプル

apiVersion: v1
kind: Secret
metadata:
    name: keycloak-db-secret
    namespace: keycloak
stringData:
    POSTGRES_DATABASE: <Database Name>
    POSTGRES_EXTERNAL_ADDRESS: <External Database IP or URL (resolvable by K8s)>
    POSTGRES_EXTERNAL_PORT: <External Database Port>
    POSTGRES_PASSWORD: <Database Password>
    # Required for AWS Backup functionality
    POSTGRES_SUPERUSER: "true"
    POSTGRES_USERNAME: <Database Username>
    SSLMODE: <TLS configuration for the Database connection>
type: Opaque

以下のプロパティーは、データベースのホスト名または IP アドレスとポートを設定します。

  • POSTGRES_EXTERNAL_ADDRESS - 外部データベースの IP アドレスまたはホスト名。
  • POSTGRES_EXTERNAL_PORT - (必要に応じて) データベースポート。

他のプロパティーは、ホストされたデータベースまたは外部データベースと同じ方法で機能します。以下のように設定します。

  • POSTGRES_DATABASE - 使用されるデータベース名。
  • POSTGRES_USERNAME - データベースのユーザー名
  • POSTGRES_PASSWORD - データベースのパスワード
  • POSTGRES_SUPERUSER - バックアップがスーパーユーザーとして実行されるかどうかを示します。通常は true です。
  • ssl_MODE: 外部 PostgreSQL データベースへの接続で TLS を使用するかどうかを示します。使用できる を確認します。

SSL_MODE を有効にすると、Operator は PostgreSQL データベースが使用する root.crt が含まれる keycloak-db-ssl-cert-secret というシークレットを検索します。シークレットの作成は任意で、データベースの証明書を検証する場合にのみシークレットが使用されます(例: SSLMODE: verify-ca)。以下に例を示します。

Operator によって使用される TLS Secret の YAML ファイルのサンプル。

apiVersion: v1
kind: Secret
metadata:
  name: keycloak-db-ssl-cert-secret
  namespace: keycloak
type: Opaque
data:
  root.crt: {root.crt base64}

Operator は keycloak-postgresql という名前のサービスを作成します。このサービスは、POSTGRES_EXTERNAL_ADDRESS のコンテンツに基づいて外部データベースを公開するように、Operator によって設定されます。Red Hat Single Sign-On は、このサービスを使用してデータベースに接続します。つまり、データベースに直接接続するのではなく、このサービスを介して接続します。

Keycloak カスタムリソースには、外部データベースのサポートを有効にするために更新が必要です。

外部データベースをサポートする Keycloak カスタムリソースの YAML ファイルの例

apiVersion: keycloak.org/v1alpha1
kind: Keycloak
metadata:
  labels:
      app: sso
  name: example-keycloak
  namespace: keycloak
spec:
  externalDatabase:
    enabled: true
  instances: 1

前提条件

  • keycloak-db-secret の YAML ファイルがある。
  • Keycloak カスタムリソースを変更して externalDatabasetrue に設定している。
  • cluster-admin パーミッション、または管理者によって付与される同等のレベルのパーミッションがある。

手順

  1. PostgreSQL データベースのシークレットを検索します (oc get secret <secret_for_db> -o yaml)。以下は例になります。

    $ oc get secret keycloak-db-secret -o yaml
    apiVersion: v1
    data
      POSTGRES_DATABASE: cm9vdA==
      POSTGRES_EXTERNAL_ADDRESS: MTcyLjE3LjAuMw==
      POSTGRES_EXTERNAL_PORT: NTQzMg==

    POSTGRES_EXTERNAL_ADDRESS は Base64 形式です。

  2. シークレットの値をデコードします (echo "<encoded_secret>" | base64 -decode)。以下は例になります。

    $ echo "MTcyLjE3LjAuMw==" | base64 -decode
    192.0.2.3
  3. デコードされた値がデータベースの IP アドレスと一致していることを確認します。

    $ oc get pods -o wide
    NAME                        READY  STATUS    RESTARTS   AGE   IP
    keycloak-0                  1/1    Running   0          13m   192.0.2.0
    keycloak-postgresql-c8vv27m 1/1    Running   0          24m   192.0.2.3
  4. 実行中のサービスの一覧に keycloak-postgresql が表示されることを確認します。

    $ oc get svc
    NAME                 TYPE       CLUSTER-IP     EXTERNAL-IP  PORT(S)   AGE
    keycloak             ClusterIP  203.0.113.0    <none>       8443/TCP  27m
    keycloak-discovery   ClusterIP  None           <none>       8080/TCP  27m
    keycloak-postgresql  ClusterIP  203.0.113.1    <none>       5432/TCP  27m

    keycloak-postgresql サービスは、バックエンドの IP アドレスのセットにリクエストを送信します。これらの IP アドレスはエンドポイントと呼ばれます。

  5. keycloak-postgresql サービスで使用されるエンドポイントを表示して、それらがデータベースの IP アドレスを使用していることを確認します。

    $ oc get endpoints keycloak-postgresql
    NAME                  ENDPOINTS         AGE
    keycloak-postgresql   192.0.2.3.5432    27m
  6. Red Hat Single Sign-On が外部データベースで実行されていることを確認します。この例は、すべてが実行されていることを示しています。

    $ oc get pods
    NAME                        READY  STATUS    RESTARTS   AGE   IP
    keycloak-0                  1/1    Running   0          26m   192.0.2.0
    keycloak-postgresql-c8vv27m 1/1    Running   0          36m   192.0.2.3

11.9. 外部の Red Hat Single Sign-On への接続

この演算子を使用して、外部の Red Hat Single Sign-On インスタンスを部分的に管理できます。現在の状態では、クライアントのみを作成できます。

これには、ターゲットおよび設定に使用する Keycloak および KeycloakRealm CRD の管理対象バージョンを作成する必要があります。

external-keycloakの YAML ファイルサンプル

apiVersion: keycloak.org/v1alpha1
kind: Keycloak
metadata:
  name: external-ref
  labels:
    app: external-sso
spec:
  unmanaged: true
  external:
    enabled: true
    url: https://some.external.url

この keycloak に対して認証するため、Operator は CRD 名を credential- でプレフィックスして CRD からシークレット名を推測します。

credential-external-refの YAML ファイルの例

apiVersion: v1
kind: Secret
metadata:
  name: credential-external-ref
type: Opaque
data:
  ADMIN_USERNAME: YWRtaW4=
  ADMIN_PASSWORD: cGFzcw==

external-realmの YAML ファイルの例

apiVersion: keycloak.org/v1alpha1
kind: KeycloakRealm
metadata:
  name: external-realm
  labels:
    app: external-sso
spec:
  unmanaged: true
  realm:
    id: "basic"
    realm: "basic"
  instanceSelector:
    matchLabels:
      app: external-sso

通常どおりクライアントでレルム参照を使用できるようになりました。これにより、外部の Red Hat Single Sign-On インスタンスにクライアントが作成されます。

11.10. データベースバックアップのスケジューリング

警告

バックアップ CR は非推奨であり、将来のリリースで削除される可能性があります。

Operator を使用して、カスタムリソースで定義されるデータベースの自動バックアップをスケジュールできます。カスタムリソースは、バックアップジョブをトリガーし、そのステータスを報告します。

Operator を使用して、ローカルの永続ボリュームへのワンタイムバックアップを実行するバックアップジョブを作成できます。

バックアップカスタムリソースの YAML ファイルの例

apiVersion: keycloak.org/v1alpha1
kind: KeycloakBackup
metadata:
  name: test-backup

前提条件

  • このカスタムリソースの YAML ファイルがある。
  • Red Hat Single Sign-On Operator によって作成される PersistentVolumeClaim についてのみ予約する claimRefPersistentVolume が必要です。

手順

  1. バックアップジョブ (oc create -f <backup_crname>) を作成します。以下は例になります。

    $ oc create -f one-time-backup.yaml
    keycloak.keycloak.org/test-backup

    Operator は、Keycloak-backup-<CR-name> という命名スキームを使用して PersistentVolumeClaim を作成します。

  2. ボリュームの一覧を表示します。

    $ oc get pvc
    NAME                          STATUS   VOLUME
    keycloak-backup-test-backup   Bound    pvc-e242-ew022d5-093q-3134n-41-adff
    keycloak-postresql-claim      Bound    pvc-e242-vs29202-9bcd7-093q-31-zadj
  3. バックアップジョブの一覧を表示します。

    $ oc get jobs
    NAME           COMPLETIONS     DURATION     AGE
    test-backup    0/1             6s           6s
  4. 実行したバックアップジョブの一覧を表示します。

    $ oc get pods
    NAME                               READY    STATUS       RESTARTS    AGE
    test-backup-5b4rf                  0/1      Completed    0           24s
    keycloak-0                         1/1      Running      0           52m
    keycloak-postgresql-c824c6-vv27m   1/1      Running      0           71m
  5. 完了したバックアップジョブログを表示します。

    $ oc logs test-backup-5b4rf
    ==> Component data dump completed
    .
    .
    .
    .

関連資料

11.11. 拡張機能とテーマのインストール

Operator を使用して、エクステンションおよび会社または組織に必要な拡張機能をインストールできます。エクステンションまたはテーマは、Red Hat Single Sign-On が使用できる任意のものになります。たとえば、メトリクス拡張を追加できます。エクステンションまたはテーマを Keycloak カスタムリソースに追加します。

Keycloak カスタムリソースの YAML ファイルのサンプル

apiVersion: keycloak.org/v1alpha1
kind: Keycloak
metadata:
  name: example-keycloak
  labels:
   app: sso
spec:
  instances: 1
  extensions:
   - <url_for_extension_or_theme>
  externalAccess:
    enabled: True

他の拡張と同じ方法でパッケージ化し、デプロイできます。詳細は、「 Deploying Themes manual entry」を参照してください。

前提条件

  • Keycloak カスタムリソースの YAML ファイルがある。
  • cluster-admin パーミッション、または管理者によって付与される同等のレベルのパーミッションがある。

手順

  1. Keycloak カスタムリソースの YAML ファイルを編集します (oc edit <CR-name>)。
  2. instances の行に extensions: という行を追加します。
  3. カスタムエクステンションまたはテーマの JAR ファイルに URL を追加します。
  4. ファイルを保存します。

Operator は拡張またはテーマをダウンロードし、これをインストールします。

11.12. カスタムリソースを管理するためのコマンドオプション

カスタムリクエストの作成後に、oc コマンドを使用してこれを編集するか、削除することができます。

  • カスタム要求を編集するには、oc edit <CR-name> コマンドを使用します。
  • カスタム要求を削除するには、コマンド oc delete <CR-name> を使用します。

たとえば、test-realm という名前のレルムカスタム要求を編集するには、次のコマンドを使用します。

$ oc edit test-realm

変更を実行できるウィンドウが開きます。

注記

Keycloak CR YAML ファイルを更新して、変更がデプロイメントに適用されます。

他のリソースへの更新は制限されます。

Keycloak Realm CR は、同期オプションなしでの基本的な作成および削除のみをサポートします。Keycloak User および Client CR は一方向更新をサポートします(CR に変更は Keycloak に反映されますが、Keycloak で実行された変更は CR で更新されません)。

11.13. アップグレードストラテジー

Operator による Red Hat Single Sign-On のアップグレード方法を設定できます。以下のアップグレードストラテジーを選択できます。

  • recreate: これはデフォルトのストラテジーです。オペレーターは、すべての Red Hat Single Sign-On レプリカを削除し、オプションでバックアップを作成し、新しい Red Hat Single Sign-On イメージに基づいてレプリカを作成します。このストラテジーは、単一の Red Hat Single Sign-On バージョンとして、基礎となるデータベースにアクセスするのに適しています。マイナス面は、アップグレード中に Red Hat Single Sign-On をシャットダウンする必要があります。
  • rolling: オペレーターは一度に 1 つのレプリカを削除し、新しい Red Hat Single Sign-On イメージに基づいて再び作成します。これにより、ゼロダウンタイムのアップグレードが確保されますが、データベースの移行を必要としないマイナーバージョンアップグレードには、複数の Red Hat Single Sign-On バージョンが同時にアクセスされるため、データベースの移行は必要ありません。このストラテジーでは、自動バックアップはサポートされていません。

Keycloak カスタムリソースの YAML ファイルのサンプル

apiVersion: keycloak.org/v1alpha1
kind: Keycloak
metadata:
  name: example-keycloak
  labels:
   app: sso
spec:
  instances: 2
  migration:
    strategy: recreate
    backups:
      enabled: True
  externalAccess:
    enabled: True

注記

以前のバージョンの Operator で導入された バグ により、Red Hat Single Sign-On StatefulSet の Selector フィールドは、設定に応じて誤って設定される可能性があります。このような状態が Operator によって検出され、再作成 ストラテジーを使用している場合、StatefulSet が正しい Selector フィールドで削除および再作成 されます。これは、Selector フィールドが変更できないため、必要になります。

「削除」操作では、Operator が StatefulSet 定義に認識されないカスタム機能を追加すると、手動で StatefulSet を削除できます。