Keycloakのクライアントポリシー（Client Policies）

第2回となる今回は、FAPIをはじめとしたさまざまなセキュリティプロファイルを柔軟にサポートするための仕組みとして開発された、クライアントポリシー（Client Policies）についてご紹介します。

Client Policiesとは

Client Policiesとは、特定の条件を満たすクライアントからKeycloakへのリクエストに対して、特定の処理を実施する機能です。Keycloakが管理するクライアントには多数の設定項目があります。この設定項目は、標準仕様で定義されているもの（Client Metadata^{※1 ※2}）もあれば、Keycloak固有のものもあります。この設定値に応じてKeycloakはクライアントからのリクエストに対して適用する処理を変えることができます。クライアントからのリクエストに対し、ある一定のセキュリティレベルを課す処理をKeycloakが行いたい場合、そのようにクライアントの設定をKeycloak上で正しく行う必要があります。クライアントが多数ある場合には、それらすべてに対して正しく設定を行う必要があり、Keycloakの管理者の負担が増えます。また、正しい設定を見出すためにはセキュリティの専門知識が必要な場合があり、そのような専門知識がない場合、誤った設定を行う恐れがあります。Client Policiesを利用することで、こういった難点を解消できます。Client Policiesでは、Profileという形である一定のセキュリティレベルを課す処理を定義し、Policyという形でそのProfileを適用するクライアントからのリクエストの条件を定義します。

本記事の執筆時点でのKeycloakの最新バージョンは15.0.2ですが、デフォルトで以下3つのProfileを提供しています。いずれも、OAuth2ベースのAPIアクセスに対するセキュリティ仕様（セキュリティプロファイル）で、OpenID Foundationが規定しています。

※1 https://datatracker.ietf.org/doc/html/rfc7591
※2 https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#client-metadata

fapi-1-baseline

Financial-grade API Security Profile 1.0 - Part 1: Baselineというセキュリティプロファイルです。

fapi-1-advanced

Financial-grade API Security Profile 1.0 - Part 2: Advancedというセキュリティプロファイルです。

fapi-ciba

Financial-grade API: Client Initiated Backchannel Authentication Profileというセキュリティプロファイルです。

Keycloakの管理者は、予め用意されたこれらのProfileを利用することで、FAPIのセキュリティプロファイルをクライアントのリクエストに対して適用することができます。Policyを利用することで、個々のクライアントに対して設定を行うことなく、Profileによって定義されるセキュリティレベルを課す処理を、クライアントのリクエストに対して行うことができます。

Client PoliciesによるFAPIの適用

本節では、実際にClient Policiesを利用してFAPI Advanced Security Profile 1.0をクライアントに対して適用する方法を示します。そして、このセキュリティプロファイルに従ってKeycloakが動作することを示します。

Profileの確認

FAPI Advanced Security Profile 1.0のProfileは、Keycloakがデフォルトで提供しています。KeycloakのAdmin Consoleにて、「Realm Settings」をクリック後、「Client Policies」タブをクリックします。次いで、「Profiles」タブをクリックし、さらに「Form View」をクリックします。すると、図1に示されるように、レルムに登録されているProfileの一覧が表示されます。

図1：Profileの一覧

「fapi-1-advanced」がFAPI Advanced Security Profile 1.0のProfileです。これをクリックすると、図2に示されるように、Profileの説明と、Profileを構成するExecutor ^※3 の一覧が表示されます。

図2：Profileの設定

※3 セキュリティプロファイルを構成する個々のセキュリティ関係の処理を行うコンポーネント。

このProfileはKeycloakがデフォルトで提供するもので、変更はできません。またProfileを構成するExecutorの追加・削除・変更も行えません。Profileを構成するExecutorをクリックするか、「Edit」ボタンを押下すると、図3で示されるように、Executorの参照画面が現れます。

図3：Executorの設定

Executorにはさまざまなものがあります。図3で示されるExecutorは、特定のクライアント認証方式以外でクライアントが認証を試みた場合に、これを拒否するものです。

Policyの作成

以下の条件を満たすクライアントからのリクエストに対して、FAPI Advanced Security Profile 1.0のProfileである、fapi-1-advancedを適用します。

• Admin REST APIにより登録されるクライアントからのリクエスト
• Client Role "fapi1adv"が付与されたクライアントからのリクエスト

KeycloakのAdmin Consoleにて「Realm Settings」をクリック後、「Client Policies」タブをクリックします。次いで、「Policies」タブをクリックし、さらに「Form View」をクリックします。すると、図4に示されるように、レルムに登録されているPolicyの一覧が表示されます。デフォルトでは、Policyは存在しません。

図4：Policyの一覧

前述の条件を示すPolicyを作成します。「Create」ボタンを押下しますと、図5に示されるように、新しくPolicyを作成する画面が現れます。

図5：Policyの作成

「Save」ボタンを押下すると、Policyが作成され、図6に示されるように、Policyの説明とPolicyを構成するCondition ^※4 の一覧、およびPolicyが適用されるクライアントからのリクエストに適用されるProfileの一覧が表示されます。Policyを作成した直後は、双方とも空です。

図6：Policyの設定

※4 クライアントからのリクエストがセキュリティプロファイルの適用対象であるかどうかを決めるコンポーネント。Conditionの集合がPolicyであり、実際はPolicyでセキュリティプロファイルの適用対象であるかどうかを決める。

まず、Admin REST APIにより登録されるクライアントからのリクエストに適用されるConditionを作成します。「Create」ボタンを押下しますと、Conditionを作成する画面が現れます。「Condition Type」プルダウンから、client-update-contextを選択します。すると、図7に示されるように、Conditionの設定画面が現れます。

図7：Condition : Admin REST APIにより登録されるクライアントからのリクエスト

「Update Client Context」欄に、ByAuthenticatedUserのみを入力し、「Save」ボタンを押下します。次いで、ロール「fapi1adv」が付与されたクライアントからのリクエストに適用されるConditionを作成します。「Create」ボタンを押下しますと、Conditionを作成する画面が現れます。「Condition Type」プルダウンから、client-rolesを選択します。すると、図8に示されるように、Conditionの設定画面が現れます。

図8：Condition : Client Role "fapi1adv"が付与されたクライアントからのリクエスト

「Client Roles」欄にfapi1advを入力し、「Save」ボタンを押下します。最後に、作成したPolicyに、デフォルトのProfileであるfapi-1-advancedを追加します。図9に示されるPolicyの設定画面にて、「Client Profiles」欄の「Add client profile …」プルダウンから、fapi-1-advancedを選択します。

Policyの作成は以上になります。

動作確認

前述のPolicyの適用前と適用後それぞれで、FAPI 1.0 Advanced Security Profileに沿っていない認可リクエストをKeycloakに送信した場合にどのような動作になるかを示します。FAPI 1.0 Advanced Security Profileでは、認可リクエストにJWSで署名されたリクエストオブジェクト ^※5 を利用することが要求されています。そこで、まずPolicyを適用以前に、リクエストオブジェクトを付与せずに認可リクエストをKeycloakに送信してみます。すると、図10に示されるようにKeycloakから認証画面が現れます。

図10：認証画面

※5 認可要求のパラメータを、JSON Web Token形式で表現したもの。OpenID Connect Core 1.0の6節にて定義。

このように、Policy適用前のKeycloakは、リクエストオブジェクトを付与せずに送信されてきた認可リクエストに対して、正常応答をしています。

次に、Policyを適用後に、同じくリクエストオブジェクトを付与せずに認可リクエストをKeycloakに送信すると、下記のようにKeycloakからはクライアントのRedirect URIにエラーを示す内容をリダイレクトするよう応答が返ってきます。

https://oideyasu.example.com/cb?error=invalid_request&error_description=Missing+parameter%3A+%27request%27+or+%27request_uri%27&state=Ckdjf6

このように、Policy適用後のKeycloakはFAPI 1.0 Advanced Security Profileに従い、リクエストオブジェクトを付与せずに送信されてきた認可リクエストに対して、エラー応答しています。

第2回では、Keycloakのクライアントポリシー（Client Policies）をご紹介しました。次回は、FAPI 1.0に準拠したクライアントアプリケーションおよびリソースサーバーを利用する場合の、Keycloakの各種設定方法をご紹介します。