bin/kc.[sh|bat] start --hostname my.keycloak.orgデフォルトでは、Keycloak は hostname オプションの設定を必須とし、URL を動的に解決しません。これはセキュリティ対策です。
Keycloak は、OIDC Discovery エンドポイントや、メール内のパスワードリセットリンクの一部として、自身の URL を自由に開示します。ホスト名がホスト名ヘッダーから動的に解釈された場合、攻撃者にメール内の URL を操作し、ユーザーを攻撃者の偽のドメインにリダイレクトさせ、アクション トークンやパスワードなどの機密データを盗む機会を与える可能性があります。
hostname オプションを明示的に設定することで、不正な発行者によってトークンが発行される状況を回避できます。サーバーは、次のコマンドを使用して明示的なホスト名で起動できます。
bin/kc.[sh|bat] start --hostname my.keycloak.org| これらの例では、通信を保護するために公開証明書と秘密鍵を必要とする本番モードで Keycloak インスタンスを起動します。詳細については、Configuring Keycloak for production を参照してください。 |
前の例で示したように、スキームとポートは明示的に必須ではありません。そのような場合、Keycloak はこれらの側面を自動的に処理します。たとえば、与えられた例では、サーバーは https://my.keycloak.org:8443 でアクセス可能になります。ただし、リバースプロキシは通常、Keycloak をデフォルトポート (例: 443) で公開します。その場合、URL の部分を動的に保つのではなく、hostname オプションで完全な URL を指定することが望ましいです。サーバーは次のコマンドで起動できます。
bin/kc.[sh|bat] start --hostname https://my.keycloak.org同様に、リバースプロキシが Keycloak を異なるコンテキストパスで公開する場合があります。hostname オプションと hostname-admin オプションを介して、それを反映するように Keycloak を構成できます。次の例を参照してください。
bin/kc.[sh|bat] start --hostname https://my.keycloak.org:123/authKeycloak は、バックチャネルリクエスト用に別の URL を提供する機能を備えており、フロントチャネルリクエスト用にパブリック URL の使用を維持しながら、内部通信を可能にします。さらに、バックチャネルは、受信ヘッダーに基づいて動的に解決されます。次の例を検討してください。
bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-backchannel-dynamic trueこのようにして、クライアントと呼ばれるアプリケーションはローカルネットワーク経由で Keycloak に接続でき、サーバーは https://my.keycloak.org でパブリックにアクセス可能なままになります。
ご覧のとおり、HTTPS プロトコルはデフォルトの選択であり、Keycloak のセキュリティのベストプラクティスへのコミットメントに準拠しています。ただし、Keycloak は、必要に応じてユーザーが HTTP を選択できる柔軟性も提供します。これは、HTTP リスナーを指定するだけで実現できます。詳細については、Configuring TLS を参照してください。エッジ TLS 終端プロキシを使用すると、サーバーを次のように起動できます。
bin/kc.[sh|bat] start --hostname https://my.keycloak.org --http-enabled trueこの構成の結果、HTTPS 経由で https://my.keycloak.org で Keycloak に引き続きアクセスでき、プロキシは HTTP とポート 8080 を使用してインスタンスと対話します。
プロキシが http リクエストまたは再暗号化された TLS リクエストを転送する場合、proxy-headers オプションを設定する必要があります。ホスト名設定によっては、URL の一部またはすべてが動的に決定される場合があります。
forwarded または xforwarded のいずれかが選択されている場合は、リバースプロキシが Forwarded ヘッダーまたは X-Forwarded-* ヘッダーをそれぞれ適切に設定および上書きしていることを確認してください。これらのヘッダーを設定するには、リバースプロキシのドキュメントを参照してください。構成を誤ると、Keycloak がセキュリティ脆弱性にさらされることになります。 |
たとえば、リバースプロキシが Forwarded ヘッダーを正しく設定し、ホスト名をハードコードしたくない場合、Keycloak はこれに対応できます。サーバーを次のように起動するだけで済みます。
bin/kc.[sh|bat] start --hostname-strict false --proxy-headers forwardedこの構成では、サーバーは Forwarded ヘッダーによって設定された値を尊重します。これは、すべてのエンドポイントが動的に解決されることも意味します。
管理コンソールを別のホストで公開する場合は、次のコマンドで実行できます。
bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-admin https://admin.my.keycloak.org:8443これにより、バックエンドが https://my.keycloak.org を引き続き使用している間、https://my.keycloak.org で Keycloak に、https://admin.my.keycloak.org:8443 で管理コンソールにアクセスできます。
| ホスト名オプションとプロキシオプションは、サーバーがリッスンするポートを変更しないことに注意してください。代わりに、プロキシの前面で使用される JavaScript や CSS リンク、OIDC well-known エンドポイント、リダイレクト URI などの静的リソースのポートのみを変更します。サーバーがリッスンしている実際のポートを変更するには、HTTP 構成オプションを使用する必要があります。詳細については、All configuration を参照してください。 |
hostname-admin オプションを使用しても、hostname オプションで指定されたフロントエンド URL を介して Administration REST API エンドポイントにアクセスすることを防ぐことはできません。Administration REST API へのアクセスを制限する場合は、リバースプロキシレベルで実行する必要があります。管理コンソールは、hostname-admin オプションで指定された URL を使用して API に暗黙的にアクセスします。 |
Keycloak は、それぞれ異なる目的を持ついくつかのエンドポイントを公開しています。これらは通常、アプリケーション間の通信またはサーバーの管理に使用されます。ここでは、3 つの主要なエンドポイントグループを認識します。
フロントエンド
バックエンド
管理
これらのエンドポイントのいずれかを使用する場合は、ベース URL を設定する必要があります。ベース URL は、いくつかの部分で構成されています。
スキーム (例: https プロトコル)
ホスト名 (例: example.keycloak.org)
ポート (例: 8443)
パス (例: /auth)
各グループのベース URL は、トークンが発行および検証される方法、ユーザーを Keycloak にリダイレクトする必要があるアクション (たとえば、メールリンクを介してパスワードをリセットする場合) のリンクが作成される方法、および最も重要なこととして、アプリケーションが realms/{realm-name}/.well-known/openid-configuration から OpenID Connect Discovery Document をフェッチするときにこれらのエンドポイントを検出する方法に重要な影響を与えます。
ユーザーとアプリケーションは、フロントチャネルを介して Keycloak にアクセスするためにフロントエンド URL を使用します。フロントチャネルは、パブリックにアクセス可能な通信チャネルです。たとえば、ブラウザベースのフロー (ログインページへのアクセス、パスワードをリセットするためのリンクのクリック、またはトークンのバインド) は、フロントチャネルリクエストと見なすことができます。
フロントエンド URL 経由で Keycloak にアクセスできるようにするには、hostname オプションを設定する必要があります。
bin/kc.[sh|bat] start --hostname my.keycloak.orgバックエンドエンドポイントは、パブリックドメインまたはプライベートネットワークを介してアクセスできるものです。これらは、Keycloak とクライアント (Keycloak によって保護されたアプリケーション) 間の直接的なバックエンド通信に関連しています。このような通信は、リバースプロキシを回避して、ローカルネットワーク経由で行われる場合があります。このグループに属するエンドポイントの例としては、認証エンドポイント、トークンおよびトークンイントロスペクションエンドポイント、userinfo エンドポイント、JWKS URI エンドポイントなどがあります。
hostname-backchannel-dynamic オプションのデフォルト値は false です。これは、バックチャネル URL がフロントチャネル URL と同じであることを意味します。受信リクエストヘッダーからのバックチャネル URL の動的解決は、次のオプションを設定することで有効にできます。
bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-backchannel-dynamic truehostname オプションは URL に設定する必要があることに注意してください。詳細については、以下の Validations セクションを参照してください。
ベースフロントエンド URL と同様に、管理コンソールのリソースとエンドポイントのベース URL を設定することもできます。サーバーは、特定の URL を使用して管理コンソールと静的リソースを公開します。この URL は、リダイレクト URL、リソース (CSS、JS) のロード、Administration REST API などに使用されます。これは、hostname-admin オプションを設定することで実行できます。
bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-admin https://admin.my.keycloak.org:8443繰り返しますが、hostname オプションは URL に設定する必要があります。詳細については、以下の Validations セクションを参照してください。
前のセクションで示したように、URL はいくつかの方法で解決できます。動的に生成したり、ハードコードしたり、または両方の組み合わせにしたりできます。
受信リクエストからの動的
ホストヘッダー、スキーム、サーバーポート、コンテキストパス
プロキシ設定ヘッダー: Forwarded および X-Forwarded-*
ハードコード
サーバー全体の構成 (例: hostname、hostname-admin など)
フロントエンド URL のレルム構成
hostname URL および hostname-admin URL は、スキームとホスト名を含む完全な URL が使用されていることが検証されます。ポートは存在する場合にのみ検証され、それ以外の場合は、指定されたプロトコルのデフォルトポート (80 または 443) が想定されます。
本番プロファイル (kc.sh|bat start) では、--hostname または --hostname-strict false のいずれかを明示的に構成する必要があります。
これは、--hostname-strict false がデフォルト値である開発プロファイル (kc.sh|bat start-dev) には適用されません。
--hostname が構成されていない場合
hostname-backchannel-dynamic は false に設定する必要があります。
hostname-strict は false に設定する必要があります。
hostname-admin が構成されている場合、hostname は URL (ホスト名だけでなく) に設定する必要があります。そうしないと、管理コンソールにアクセスするときに、Keycloak は正しいフロントエンド URL (ポートなどを含む) を認識できません。
hostname-backchannel-dynamic が true に設定されている場合、hostname は URL (ホスト名だけでなく) に設定する必要があります。そうしないと、動的に解決されたバックチャネル経由でアクセスされたときに、Keycloak は正しいフロントエンド URL (ポートなどを含む) を認識できません。
さらに、ホスト名が構成されている場合、hostname-strict は無視されます。
ホスト名構成のトラブルシューティングを行うには、専用のデバッグツールを使用できます。これは次のように有効にできます。
bin/kc.[sh|bat] start --hostname=mykeycloak --hostname-debug=trueKeycloak が正常に起動したら、ブラウザを開いて次の URL にアクセスします: http://mykeycloak:8080/realms/<your-realm>/hostname-debug