リバースプロキシの使用

Keycloakはデフォルトで次のポートで実行されます

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

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

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

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

例

クライアントアドレスが Forwarded ヘッダーまたは X-Forwarded-For ヘッダーを介してリバースプロキシによって適切に設定されていることを確認するために、特別な予防措置を講じてください。このヘッダーが正しく構成されていない場合、不正なクライアントがこのヘッダーを設定し、クライアントが実際のアドレスとは異なるIPアドレスから接続されているとKeycloakに誤認させることができます。IPアドレスの拒否または許可リストを作成する場合、この予防措置はより重要になる可能性があります。

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

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

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

一般的なクラスタデプロイメントは、ロードバランサー (リバースプロキシ) とプライベートネットワーク上の2台以上のKeycloakサーバーで構成されています。パフォーマンス上の理由から、ロードバランサーが特定のブラウザセッションに関連するすべてのリクエストを同じKeycloakバックエンドノードに転送すると役立つ場合があります。

その理由は、Keycloakが現在の認証セッションとユーザーセッションに関連するデータを保存するために、Infinispan分散キャッシュを内部で使用しているためです。Infinispan分散キャッシュは、オーナーの数が制限されて構成されています。つまり、セッション関連データは一部のクラスタノードにのみ格納され、他のノードがデータにアクセスするにはリモートでデータを検索する必要があります。

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

特定のセッションエンティティが常にローカルで利用可能な場合は有益です。これは、スティッキーセッションを使用することで実現できます。パブリックフロントエンドロードバランサーと2つのバックエンドKeycloakノードを備えたクラスタ環境でのワークフローは次のようになります。

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

スティッキーセッションはクラスタ構成には必須ではありませんが、上記の理由からパフォーマンスに優れています。ロードバランサーが AUTH_SESSION_ID クッキーを維持するように構成する必要があります。この変更を行うための適切な手順は、ロードバランサーによって異なります。

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

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

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

リバースプロキシ/ゲートウェイのパブリックAPIのルートパス / でKeycloakを実行することを前提としています。そうでない場合は、パスに目的のプレフィックスを付けます。

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

例

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

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

例

プロキシがTLS終端プロキシとして構成されている場合、クライアント証明書情報を特定のHTTPリクエストヘッダーを介してサーバーに転送し、クライアントの認証に使用できます。使用しているプロキシに応じて、サーバーがクライアント証明書情報を取得する方法を構成できます。

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

リクエストからクライアント証明書を取得する方法を構成するには、次のことを行う必要があります。

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

プロバイダーを構成するために使用可能なオプションは次のとおりです。