Red Hat Summit第9章 ポリシーエンフォーサー
Policy Enforcement Point (PEP: Policy Enforcement Point) は、異なる方法で実装できる設計パターンです。Red Hat build of Keycloak は、さまざまなプラットフォーム、環境、およびプログラミング言語に PEP を実装するのに必要な方法をすべて提供します。Red Hat build of Keycloak Authorization Services は RESTful API を提供し、一元化された認可サーバーを使用して詳細な認可に OAuth2 認可機能を活用します。
PEP は、保護されているリソースに関連付けられたポリシーを評価して、Red Hat build of Keycloak サーバーからアクセス決定を強制します。これは、保護されたリソースへの特定の要求を満たすかどうかをチェックするためにアプリケーションのフィルターやインターセプターとして機能します。この決定によって付与されるパーミッションに基づいて、保護されるリソースへの特定のリクエストを満たすことができるかどうかを確認します。
Red Hat build of Keycloak は、JakartaEE 準拠のフレームワークと Web コンテナーを保護するために、Java アプリケーションに対する Red Hat build of Keycloak ポリシーエンフォーサー を有効にするビルトインサポートを提供します。Maven を使用している場合は、プロジェクトに次の依存関係を設定する必要があります。
<dependency>
<groupId>org.keycloak</groupId>
<artifactId>keycloak-policy-enforcer</artifactId>
<version>${keycloak.version}</version>
</dependency>ポリシーエンフォーサーを有効にすると、アプリケーションに送信されたリクエストはすべてインターセプトされ、そのリクエストを送信しているアイデンティティーに対して Red Hat build of Keycloak が付与したパーミッションに応じて、保護されたリソースへのアクセスが付与されます。
ポリシーの適用は、アプリケーションのパスと、Red Hat build of Keycloak の管理コンソールを使用してリソースサーバー用に作成した リソース に強く連動しています。デフォルトではリソースサーバーを作成すると、ポリシーの適用をすぐに有効にできるように、Red Hat build of Keycloak はリソースサーバーの デフォルト設定 を作成します。
9.1. 設定
ポリシーエンフォーサの設定では JSON 形式が使用されます。リソースサーバーから利用可能なリソースに基づいて保護されたパスを自動的に解決する場合、ほとんどの場合は何も設定する必要はありません。
保護するリソースを手動で定義する場合は、もう少し詳細な形式を使用できます。
{
"enforcement-mode" : "ENFORCING",
"paths": [
{
"path" : "/users/*",
"methods" : [
{
"method": "GET",
"scopes" : ["urn:app.com:scopes:view"]
},
{
"method": "POST",
"scopes" : ["urn:app.com:scopes:create"]
}
]
}
]
}以下は、各設定オプションの説明です。
enforcement-mode
ポリシーの適用方法を指定します。
ENFORCING
(デフォルトモード) 指定のリソースにポリシーが関連付けられていない場合を含め、リクエストはデフォルトで拒否されます。
PERMISSIVE
指定のリソースにポリシーが関連付けられていない場合を含め、リクエストは許可されます。
DISABLED
ポリシーの評価を完全に無効にし、すべてのリソースにアクセスできるようにします。
enforcement-modeがDISABLEDの場合、アプリケーションは 認可コンテキスト を介して Red Hat build of Keycloak が付与したすべてのパーミッションを取得できます。
on-deny-redirect-to
"access denied" メッセージがサーバーから取得される際に、クライアントリクエストがリダイレクトされる URL を定義します。デフォルトでは、アダプターは 403 HTTP ステータスコードで応答します。
path-cache
ポリシーエンフォーサーが、Red Hat build of Keycloak で定義したアプリケーションとリソース間の関連付けを追跡する方法を定義します。このキャッシュは、パスと保護リソース間の関連付けをキャッシュすることで、Red Hat build of Keycloak サーバーへの不要なリクエストを回避するために必要です。
有効期間
エントリーの期限が切れる時間 (ミリ秒単位) を定義します。指定しないと、デフォルト値は 30000 になります。0 に等しい値を設定して、キャッシュを完全に無効にすることができます。-1 に等しい値を設定して、キャッシュの有効期限を無効にすることができます。
max-entries
キャッシュに保持される必要があるエントリーの制限を定義します。指定しないと、デフォルト値は 1000 になります。
paths
保護するパスを指定します。この設定はオプションです。定義されていない場合、ポリシーエンフォーサーは Red Hat build of Keycloak でアプリケーションに定義したリソースを取得してすべてのパスを検出します。これらのリソースは、アプリケーション内の一部のパスを表す
URISで定義されます。name
指定のパスに関連付けられるサーバー上のリソースの名前。path と併用される場合、ポリシーエンフォーサーはリソースの URIS プロパティーを無視し、代わりに指定したパスを使用します。
path
(必須) アプリケーションのコンテキストパスに相対する URI。このオプションが指定されていると、ポリシーは、同じ値を持つ URI でリソースについて、サーバーに対してクエリーを実行します。現在、パス照合に非常に基本的なロジックがサポートされています。有効なパスの例は以下のとおりです。
-
ワイルドカード:
/* -
接尾辞:
/*.html -
サブパス:
/path/* - パスパラメーター: /resource/{id}
- 完全一致: /resource
- パターン: /{version}/resource, /api/{version}/resource, /api/{version}/resource/*
-
ワイルドカード:
methods
HTTP メソッド (GET、POST、PATCH など) は、サーバーの特定リソースのスコープとどのように関連付けされるかを指定します。
method
HTTP メソッドの名前。
scopes
メソッドに関連付けられたスコープを持つ文字列の配列。スコープを特定のメソッドに関連付ける際に、保護されたリソース (またはパス) へのアクセスを試みるクライアントが、リストで指定されたすべてのスコープにパーミッションを付与する RPT を提供する必要があります。たとえば、スコープ 作成 でメソッド POST を定義する場合、パスへの POST を実行する際に、RPT には create スコープへのアクセスを付与するパーミッションが含まれている必要があります。
scopes-enforcement-mode
メソッドに関連付けられたスコープの強制モードを参照する文字列。値は、ALL または ANY にすることができます。ALL の場合は、このメソッドを使用してリソースにアクセスするために定義されたすべてのスコープが付与される必要があります。ANY の場合は、このメソッドを使用してリソースにアクセスするには、少なくとも 1 つのスコープを付与する必要があります。デフォルトでは、強制モードは ALL に設定されます。
enforcement-mode
ポリシーの適用方法を指定します。
ENFORCING
(デフォルトモード) 指定されたリソースに関連付けられたポリシーがない場合でも、要求はデフォルトで拒否されます。
- DISABLED
claim-information-point
これらの要求をポリシーで利用可能にするために解決し、Red Hat build of Keycloak サーバーにプッシュする必要のある 1 つ以上の要求のセットを定義します。詳細は、要求情報ポイント を参照してください。
lazy-load-paths
アプリケーションがパスに関連付けられたリソースのサーバーを取得する方法を指定します。true の場合、ポリシーエンフォーサーは要求されるパスに応じてオンデマンドでリソースをフェッチします。この設定は、デプロイメント中にサーバーからすべてのリソースを取得する場合 (
pathsを指定しなかった場合) や、pathsのサブセットのみが定義されていて、他をオンデマンドで取得する場合などに特に便利です。http-method-as-scope
スコープを HTTP メソッドにマッピングする方法を指定します。true に設定すると、ポリシーエンフォーサーは現在のリクエストから HTTP メソッドを使用して、アクセスを付与すべきかどうかを確認します。有効にした場合、Red Hat build of Keycloak のリソースが保護している各 HTTP メソッドを表すスコープに関連付けられていることを確認してください。
claim-information-point
これらの要求をポリシーで利用可能にするために、解決して Red Hat build of Keycloak サーバーにプッシュする必要がある 1 つ以上の グローバル 要求のセットを定義します。詳細は、要求情報ポイント を参照してください。
