13.7. クライアントポリシー
クライアントアプリケーションを簡単に保護するには、以下の点を統一して認識しておくと便利です。
- クライアントの実行できる設定でのポリシーの設定
- クライアント設定の検証
- Financial-grade API (FAPI) や OAuth 2.1 などの必要なセキュリティー標準とプロファイルへの準拠
これらのポイントを統一された方法で実現するために、クライアントポリシー の概念が導入されました。
13.7.1. ユースケース リンクのコピーリンクがクリップボードにコピーされました!
クライアントポリシーでは、以下の点を実現しています。
- クライアントの実行できる設定でのポリシーの設定
- クライアントの設定は、クライアントの作成/更新中だけでなく、特定のクライアントに関連する Red Hat build of Keycloak サーバーへの OpenID Connect 要求時にも、クライアントポリシーで適用できます。Red Hat build of Keycloak は、アプリケーションおよびサービスの保護ガイド の クライアント登録サービス で説明されている クライアント登録ポリシー を通じても同様のことをサポートします。ただし、クライアント登録ポリシーは、OIDC 動的クライアント登録のみに対応します。クライアントポリシーは、クライアント登録ポリシーが実行できるものだけでなく、他のクライアント登録および設定方法もカバーします。現在の計画では、クライアント登録はクライアントポリシーに置き換えられます。
- クライアント設定の検証
- Red Hat build of Keycloak は、認可エンドポイントやトークンエンドポイントなどの一部のエンドポイントで、クライアントが Proof Key for Code Exchange、Request Object Signing Algorithm、Holder-of-Key Token などの設定に従うかどうかの検証をサポートします。これらは、各設定項目 (管理コンソール、スイッチ、プルダウンメニューなど) で指定できます。クライアントアプリケーションをセキュアにするには、管理者が適切な方法で多くの設定を指定する必要があるため、管理者がクライアントアプリケーションのセキュリティーを保護することは困難になります。クライアントポリシーは、上記のクライアント設定に対してこれらの検証を行うことができ、高度なセキュリティー要件を満たすように、一部のクライアント設定スイッチの自動設定に使用できます。今後、個々のクライアント設定が、直接必要な検証を実行するクライアントポリシーに置き換えられる可能性があります。
- FAPI や OAuth 2.1 などの必要なセキュリティー標準とプロファイルへの準拠
- Global クライアントプロファイル は、デフォルトで Red Hat build of Keycloak に事前設定されたクライアントプロファイルです。これらは、アプリケーションの保護 セクションの FAPI や OAuth 2.1 などの標準セキュリティープロファイルに準拠するように事前設定されているため、管理者はクライアントアプリケーションを特定のセキュリティープロファイルに準拠するように簡単に保護できます。現時点では、Red Hat build of Keycloak には、FAPI および OAuth 2.1 仕様をサポートするためのグローバルプロファイルがあります。管理者は、FAPI および OAuth 2.1 に準拠する必要があるクライアントを指定する際に、クライアントポリシーを設定するだけで済みます。管理者は、クライアントプロファイルとクライアントポリシーを設定できるため、容易に Red Hat build of Keycloak クライアントを SPA、ネイティブアプリケーション、Open Banking などの他のセキュリティープロファイルに準拠させることができます。
13.7.2. プロトコル リンクのコピーリンクがクリップボードにコピーされました!
クライアントポリシーの概念は、特定のプロトコルからは独立しています。Red Hat build of Keycloak は現在、特に OpenID Connect (OIDC) プロトコル のクライアントプロファイルをサポートしていますが、SAML プロトコル 用のクライアントプロファイルも利用できます。
13.7.3. アーキテクチャー リンクのコピーリンクがクリップボードにコピーされました!
クライアントポリシーは、Condition、Executor、Profile、および Policy の 4 つのビルディングブロックで構成されます。
13.7.3.1. 条件 リンクのコピーリンクがクリップボードにコピーされました!
条件は、ポリシーが採用されるクライアントと、そのクライアントが採用されるタイミングを決定します。一部の条件は、クライアント要求 (OIDC 認可要求、トークンエンドポイント要求など) で他の条件がクライアント要求時にチェックされる場合に、クライアントの作成/更新時にチェックされます。条件は、指定基準の 1 つが満たされているかどうかを確認します。たとえば、一部の条件では、クライアントのアクセスタイプが機密であるかどうかをチェックします。
この条件は単独で使用できません。後述の ポリシー で使用できます。
他の設定可能なプロバイダーと同じ条件を設定できます。設定可能なものは、各条件の性質によって異なります。
以下の条件が提供されます。
- クライアントの作成/更新方法
- 動的クライアント登録 (初期アクセストークンまたは登録アクセストークンで認証されていない、または認証されていない)
- Admin REST API(管理コンソールなど)
たとえば、クライアントの作成時に、このクライアントが初期アクセストークンのない OIDC 動的クライアント登録 (匿名動的クライアント登録) で作成される場合に、条件が true に評価されるように設定できます。そのため、この条件は、たとえば、OIDC 動的クライアント登録により登録されたすべてのクライアントを FAPI または OAuth 2.1 に準拠させるために使用できます。
- クライアントの作成者 (特定のロールまたはグループに存在するかどうかで確認)
- OpenID Connect 動的クライアント登録では、クライアントの作成者は、認証済みのエンドユーザーで、アクセストークンを使用して登録エンドポイントに実際にアクセスする既存のクライアントのサービスアカウントではなく、新しいクライアントを生成するためのアクセストークンを取得できます。Admin REST API による登録では、クライアントの作成者は Red Hat build of Keycloak の管理者のようなエンドユーザーです。
- クライアントアクセスタイプ (機密、パブリック、bearer のみ)
- たとえば、クライアントが認可要求を送信すると、このクライアントが機密である場合はポリシーが採用されます。パブリッククライアントがクライアント認証を無効にしている場合、機密クライアントはクライアント認証を有効にしています。Bearer-only は非推奨のクライアントタイプです。
- クライアントスコープ
-
クライアントに固有のクライアントスコープがある場合 (デフォルトまたは現在のリクエストで使用される任意のスコープ) は、true と評価します。たとえば、スコープが
fapi-example-scope
の OIDC 認可要求が FAPI に準拠する必要があることを確認できます。 - クライアントロール
- 指定の名前のクライアントロールが割り当てられたクライアントに適用されます。通常、要求されたクライアントに対して指定された名前のクライアントロールを作成し、それを "マーカーロール" として使用して、要求されたクライアントに指定されたクライアントポリシーが適用されるようにすることができます。
よくあるユースケースとして、my-client-1
や my-client-2
など、指定のクライアントに対して特定のクライアントポリシーを適用することが求められます。このような結果を実現する最善の方法は、ポリシーで Client Role 条件を使用し、要求されるクライアントに対して指定の名前のクライアントロールを作成することです。このクライアントロールは、特定のクライアントの特定のクライアントポリシーをマークするためだけに使用する "マーカーロール" として使用できます。
- クライアントドメイン名、ホスト名、または IP アドレス
- クライアントの特定のドメイン名に適用されます。または、管理者が特定のホストまたは IP アドレスからクライアントを登録/更新する場合。
- クライアント属性
- 指定された名前と値のクライアント属性を持つクライアントに適用されます。複数のクライアント属性を指定すると、AND 条件を使用して評価されます。OR 条件を使用して評価する場合は、この条件を複数回設定します。
- 任意のクライアント
- この条件は常に true と評価されます。たとえば、特定のレルム内のすべてのクライアントが FAPI に準拠することを確認するために使用できます。
- ACR 条件
- 認証要求で要求された ACR 値が条件で設定された値と一致する場合に適用されます。たとえば、要求された ACR 値に基づいて認証フローを選択するために使用できます。詳細は、関連ドキュメント と 公式の OIDC 仕様 を参照してください。
- グラントタイプ
- 特定のグラントタイプが使用される場合は true と評価されます。たとえば、クライアントスコープと組み合わせて使用して、特定のクライアントスコープが要求されたときにトークン交換要求をブロックできます。
13.7.3.2. エグゼキューター (Executor) リンクのコピーリンクがクリップボードにコピーされました!
エグゼキューターは、ポリシーが採用されるクライアントで実行されるアクションを指定します。エグゼキューターは、1 つまたは複数の指定されたアクションを実行します。たとえば、一部のエクゼキューターは、認可要求のパラメーター redirect_uri
の値が Authorization Endpoint の事前登録リダイレクト URI と完全に一致するかどうかを確認し、一致しない場合はこの要求を拒否します。
エクゼキューターは、単独では使用できません。後述の プロファイル で使用できます。
エグゼキューターは、他の設定可能なプロバイダーと同じように設定できます。設定可能なものは、各エグゼキューターの性質によって異なります。
エグゼキューターはさまざまなイベントで機能します。エグゼキューターの実装は、特定の種類のイベントを無視できます (たとえば、OIDC request
オブジェクトをチェックするエグゼキューターは、OIDC 認可要求に対してのみ機能します)。イベントは以下のとおりです。
- クライアントの作成 (動的クライアント登録による作成を含む)
- クライアントの更新
- 認可要求の送信
- トークン要求の送信
- トークン更新要求の送信
- トークン失効要求の送信
- トークンイントロスペクション要求の送信
- userinfo 要求の送信
- リフレッシュトークンを使用してログアウト要求を送信します (リフレッシュトークンを使用したログアウトは、どの仕様でもサポートされていないプロプライエタリー Red Hat build of Keycloak 機能であることに注意してください)。むしろ、公式の OIDC ログアウト に頼ることを推奨します。
各イベントでは、エグゼキューターは複数のフェーズで機能します。たとえば、クライアントの作成/更新時に、エグゼキューターは特定のクライアント設定を自動設定してクライアント設定を変更できます。その後、エグゼキューターはこの設定を検証フェーズで検証します。
このエグゼキュータの目的の 1 つは、FAPI や OAuth 2.1 などのクライアント準拠プロファイルのセキュリティー要件を実現することです。これを行うには、以下のエクゼキューターが必要です。
- クライアントにセキュアな クライアント認証方式 が使用されるようにします。
- Holder-of-key トークン が使用されるようにします。
- Proof Key for Code Exchange (PKCE) が使用されるようにします。
- 署名付き JWT クライアント認証 (private-key-jwt) のセキュアな署名アルゴリズムが使用されるようにします。
- HTTPS リダイレクト URI を強制的に使用し、設定したリダイレクト URI にワイルドカードが含まれないようにします。
-
高いセキュリティーレベルを満たす OIDC
request
オブジェクトを有効にします。 - FAPI 1 仕様で説明されているように、デタッチされた署名 として使用される ID トークンを含む OIDC ハイブリッドフローの応答タイプを有効にします。つまり、認証応答から返される ID トークンにはユーザーのプロファイルデータが含まれないようにします。
-
CSRF を防止するために、よりセキュアな
state
およびnonce
パラメーターの処理を有効にします。 - クライアント登録時によりセキュアな署名アルゴリズムを有効にします。
-
binding_message
パラメーターを CIBA 要求に強制的に使用します。 - クライアントシークレットローテーション を適用します。
- クライアント登録アクセストークンを適用します。
- UK OpenBanking のようなアクセストークンを取得するための認可コードフローを開始する前にインテントが発行されるユースケースでは、クライアントがインテントの発行先であるかどうかのチェックを強制します。
- 暗黙的およびハイブリッドフローの禁止を強制します。
- PAR 要求に、認可要求に含まれる必要なパラメーターが含まれているかどうかのチェックを強制します。
-
DPoP バインディングトークン の使用を強制します (
dpop
機能が有効な場合に使用可能)。 - 軽量アクセストークンの使用 を強制します。
- リフレッシュトークンのローテーション をスキップし、リフレッシュトークンの応答からリフレッシュトークンが返されないようにします。
- OAuth 2.1 仕様で要求される有効なリダイレクト URI を強制します。
- SAML Redirect バインディングの強制は、SAML リクエストやアサーションが署名されている場合には使用できません。
別のエグゼキューターとして auth-flow-enforce
があります。これは、認証要求中に認証フローを強制する場合に使用できます。たとえば、特定のスコープや ACR 値などの特定の条件に基づいたフローの選択に使用できます。詳細は、関連ドキュメント を参照してください。
13.7.3.3. Profile リンクのコピーリンクがクリップボードにコピーされました!
プロファイルは複数のエクゼキューターで構成されます。これにより、FAPI や OAuth 2.1 などのセキュリティープロファイルを実現できます。プロファイルは、Admin REST API (Admin Console) によりエグゼキューターとともに設定できます。3 つの グローバルプロファイル が存在します。これらはデフォルトで、FAPI 1 Baseline、FAPI 1 Advanced、FAPI CIBA、FAPI 2、および OAuth 2.1 仕様に準拠した事前設定済みのエグゼキューターを使用して Red Hat build of Keycloak に設定されています。詳細は、アプリケーションのセキュリティー保護 セクションの FAPI および OAuth 2.1 を参照してください。
13.7.3.4. ポリシー リンクのコピーリンクがクリップボードにコピーされました!
ポリシーは複数の条件およびプロファイルで構成されます。このポリシーは、対象ポリシーの全条件を満たすクライアントに採用できます。このポリシーは複数のプロファイルを参照し、これらのプロファイルの全エクゼキューターは、このポリシーが採用されるクライアントに対してそのタスクを実行します。
13.7.4. 設定 リンクのコピーリンクがクリップボードにコピーされました!
ポリシー、プロファイル、条件、エグゼキューターは Admin REST API で設定できます。これは管理コンソールでもあります。これを行うために Realm
グローバルクライアントプロファイル は、各レルムで自動的に利用できます。ただし、デフォルトではクライアントポリシーは設定されません。つまり、レルムのクライアントを FAPI に準拠させる場合などに、管理者はクライアントポリシーを作成する必要があります。グローバルプロファイルは更新できませんが、管理者はそれらをテンプレートとして簡単に使用し、グローバルプロファイル設定で多少変更を加える場合は、独自のプロファイルを作成できます。管理コンソールでは JSON Editor があり、一部のグローバルプロファイルに基づいて新規プロファイルを簡単に作成できます。
13.7.5. 後方互換性 リンクのコピーリンクがクリップボードにコピーされました!
クライアントポリシーは、アプリケーションおよびサービスの保護ガイド の クライアント登録サービス で説明されているクライアント登録ポリシーを置き換えることができます。ただし、クライアント登録ポリシーは引き続き共存します。これは、クライアントの作成/更新要求時などに、クライアントポリシーとクライアント登録ポリシーの両方が適用されることを意味します。
現在の計画では、クライアント登録ポリシー機能が削除され、既存のクライアント登録ポリシーは自動的に新しいクライアントポリシーに移行されます。
13.7.6. クライアントシークレットローテーション例 リンクのコピーリンクがクリップボードにコピーされました!
クライアントシークレットローテーション の設定例を参照してください。