第5章 ホスト名の設定

フロントエンドのエンドポイントは、パブリックドメインを通じてアクセスでき、通常はフロントチャネルを通じて発生する認証/認可フローに関連します。たとえば、SPA がユーザーを認証する必要がある場合、SPA はユーザーを authorization_endpoint にリダイレクトし、ユーザーがフロントチャネル経由でブラウザーを使用して認証できるようにします。

デフォルトでは、ホスト名設定が行われていない場合、これらのエンドポイントのベース URL は受信要要求に基づくため、HTTP スキーム、ホスト、ポート、パスは要求と同じになります。発行者もフロントエンドエンドポイントに設定された URL に基づくため、デフォルトの動作は、サーバーがトークンを発行する方法にも直接影響します。ホスト名設定が行われていない場合、トークン発行者も受信要求に基づくことになり、クライアントが異なる URL を使用してトークンを要求している場合は一貫性が失われます。

通常、実稼働環境にデプロイする場合、要求の構築方法に関係なく、フロントエンドエンドポイントとトークン発行者の一貫した URL が必要になります。この一貫性を実現するために、hostname または hostname-url オプションを設定できます。

ほとんどの場合、フロントエンド URL の ホスト のみを変更するには、hostname オプションを設定するだけで十分です。

bin/kc.[sh|bat] start --hostname=<host>

hostname オプションを使用している場合、以下を達成するために、サーバーは HTTP スキーム、ポート、およびパスを自動的に解決します。

ただし、ホストだけでなくスキーム、ポート、パスも設定する必要がある場合は、hostname-url オプションを設定できます。

bin/kc.[sh|bat] start --hostname-url=<scheme>://<host>:<port>/<path>

このオプションを使用すると、1 つのオプションで URL のさまざまな部分を設定できるため、柔軟性が向上します。hostname と hostname-url は、相互に排他的であることに注意してください。

バックエンドエンドポイントは、パブリックドメインまたはプライベートネットワークを通じてアクセスできるエンドポイントです。これらは、サーバーとクライアント間の、仲介のないプレーン HTTP 要求による直接通信に使用されます。たとえば、ユーザーが認証された後、SPA はトークン要求を token_endpoint に送信することで、サーバーが送信した code をトークンセットと交換する必要があるとします。

デフォルトでは、バックエンドエンドポイントの URL も受信要求に基づいています。この動作をオーバーライドするには、次のコマンドを入力して hostname-strict-backchannel 設定オプションを設定します。

bin/kc.[sh|bat] start --hostname=<value> --hostname-strict-backchannel=true

hostname-strict-backchannel オプションを設定すると、バックエンドエンドポイントの URL はフロントエンドエンドポイントとまったく同じになります。

Red Hat build of Keycloak に接続されているすべてのアプリケーションがパブリック URL 経由で通信する場合は、hostname-strict-backchannel を true に設定します。それ以外の場合は、このパラメーターを false のままにして、プライベートネットワークを介したクライアント/サーバー通信を許可します。

サーバーは、特定の URL を使用して管理コンソールと静的リソースを公開します。

デフォルトでは、管理コンソールの URL も受信要求に基づいています。ただし、特定の URL を使用して管理コンソールへのアクセスを制限する場合は、特定のホストまたはベース URL を設定できます。フロントエンド URL の設定方法と同様に、hostname-admin および hostname-admin-url オプションを使用してこれを実現できます。HTTPS が有効になっている場合 (実稼働モードのデフォルト設定として http-enabled 設定オプションは false に設定されています)、Red Hat build of Keycloak サーバーは HTTPS URL の使用を自動的に想定することに注意してください。次に、管理コンソールは HTTPS 経由で Red Hat build of Keycloak に接続しようとします。HTTPS URL は、設定されたリダイレクト/Web オリジン URL にも使用されます。実稼働環境には推奨されませんが、HTTP URL を hostname-admin-url として使用して、この動作をオーバーライドできます。

ほとんどの場合、管理コンソール URL の ホスト のみを変更するのであれば、hostname-admin オプションを設定するだけで十分です。

bin/kc.[sh|bat] start --hostname-admin=<host>

ただし、ホストだけでなくスキーム、ポート、パスも設定する必要がある場合は、hostname-admin-url オプションを設定できます。

bin/kc.[sh|bat] start --hostname-admin-url=<scheme>://<host>:<port>/<path>

hostname-admin と hostname-admin-url は相互に排他的であることに注意してください。

攻撃対象領域を減らすために、Red Hat build of Keycloak の管理エンドポイントと管理コンソールは、パブリックにアクセスできないようにする必要があります。つまり、リバースプロキシーを使用して保護できます。リバースプロキシーを使用して公開するパスの詳細は、リバースプロキシーの使用 を参照してください。