第5章 ホスト名の設定
5.1. サーバーエンドポイント
Red Hat build of Keycloak は、アプリケーションと対話したり、管理コンソールへのアクセスを許可したりするための、さまざまなエンドポイントを公開します。これらのエンドポイントは、次の 3 つの主要なグループに分類できます。
- フロントエンド
- バックエンド
- 管理コンソール
各グループのベース URL は、トークンの発行方法と検証方法、ユーザーを Red Hat build of Keycloak にリダイレクトする必要があるアクション (メールリンクを通じてパスワードをリセットする場合など) のリンクの作成方法、さらにはアプリケーションが realms/{realm-name}/.well-known/openid-configuration から OpenID Connect Discovery Document を取得する際にこれらのエンドポイントを検出する方法に重要な影響を与えます。
5.1.1. フロントエンド
フロントエンドのエンドポイントは、パブリックドメインを通じてアクセスでき、通常はフロントチャネルを通じて発生する認証/認可フローに関連します。たとえば、SPA がユーザーを認証する必要がある場合、SPA はユーザーを authorization_endpoint にリダイレクトし、ユーザーがフロントチャネル経由でブラウザーを使用して認証できるようにします。
デフォルトでは、ホスト名設定が行われていない場合、これらのエンドポイントのベース URL は受信要要求に基づくため、HTTP スキーム、ホスト、ポート、パスは要求と同じになります。発行者もフロントエンドエンドポイントに設定された URL に基づくため、デフォルトの動作は、サーバーがトークンを発行する方法にも直接影響します。ホスト名設定が行われていない場合、トークン発行者も受信要求に基づくことになり、クライアントが異なる URL を使用してトークンを要求している場合は一貫性が失われます。
通常、実稼働環境にデプロイする場合、要求の構築方法に関係なく、フロントエンドエンドポイントとトークン発行者の一貫した URL が必要になります。この一貫性を実現するために、hostname または hostname-url オプションを設定できます。
ほとんどの場合、フロントエンド URL の ホスト のみを変更するには、hostname オプションを設定するだけで十分です。
bin/kc.[sh|bat] start --hostname=<host>
hostname オプションを使用している場合、以下を達成するために、サーバーは HTTP スキーム、ポート、およびパスを自動的に解決します。
-
hostname-strict-https=falseを設定しない限り、httpsスキームが使用されます。 -
proxy-headersオプションが設定されている場合、プロキシーがデフォルトのポート (80 と 443) を使用します。プロキシーで別のポートを使用する場合は、hostname-url設定オプションで指定する必要があります。
ただし、ホストだけでなくスキーム、ポート、パスも設定する必要がある場合は、hostname-url オプションを設定できます。
bin/kc.[sh|bat] start --hostname-url=<scheme>://<host>:<port>/<path>
このオプションを使用すると、1 つのオプションで URL のさまざまな部分を設定できるため、柔軟性が向上します。hostname と hostname-url は、相互に排他的であることに注意してください。
5.1.2. バックエンド
バックエンドエンドポイントは、パブリックドメインまたはプライベートネットワークを通じてアクセスできるエンドポイントです。これらは、サーバーとクライアント間の、仲介のないプレーン 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 のままにして、プライベートネットワークを介したクライアント/サーバー通信を許可します。
5.1.3. 管理コンソール
サーバーは、特定の 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 の管理エンドポイントと管理コンソールは、パブリックにアクセスできないようにする必要があります。つまり、リバースプロキシーを使用して保護できます。リバースプロキシーを使用して公開するパスの詳細は、リバースプロキシーの使用 を参照してください。
