OpenID Connect OAuth 2.0 トークン適用ポリシー

ポリシー名

OpenID Connect OAuth 2.0 トークン適用

概要

承認されたクライアントアプリケーションへのアクセスのみを許可する

カテゴリ

セキュリティ

使用可能な最小 Mule バージョン

v4.1.1

返される状況コード

400 - 無効なトークン

401 - 未承認または認証サーバーへの接続時にエラー

403 - アクセス拒否、無効なクライアントアプリケーションログイン情報

500 - 認証サーバーからの不正応答、または WSDL SOAP 失敗エラー (Mule のみ)。

概要

OpenID Connect アクセストークン適用ポリシーは、保護されたリソースへのアクセスを、API アクセス権を持つクライアントアプリケーションに属する有効な Oauth2 トークンを提供する HTTP 要求に制限します。このポリシーはトークンを生成せず、トークンを検証するだけです。

このポリシーは、クライアント管理ソリューションとして OpenID Connect 動的クライアント登録を使用するように設定されている組織でのみ使用できます。

ポリシーのパラメーターの設定

Mule ゲートウェイ

UI からポリシーを API に適用するときに、環境に Mule アプリケーションがあるかどうかに基づいて、パラメーターのリストが表示されます。

Mule アプリケーションと Flex Gateway のパラメーターの設定

次のパラメーターが表示されます。

要素説明例

要素	説明	例
Scopes (スコープ)	サポートされるスコープのカンマ区切りリストを表示します。	READ, WRITE, READ and WRITE
Scope Validation Criteria (スコープ検証条件)	トークンに定義済みのすべてのスコープが含まれる必要があるか、1 つのみ含まれる必要があるかを決定します。この値は、`Contains all scopes` と `Contains any scope` です。	[Contains all scopes (すべてのスコープを含む)] 値が選択されている場合、スコープ `READ` と `WRITE` を持つトークンが受け入れられます。[Contains any scopes (任意のスコープを含む)] 値が選択されている場合、スコープ `READ, WRITE, and READ AND WRITE` を持つトークンが受け入れられます。
Validate TLS Certificate (TLS 証明書の検証) (Mule のみ)	サードパーティ認証サーバーの TLS 検証を有効にします。	選択した場合、トークン検証エンドポイントとの通信には TLS プロトコルが使用されます。
Expose Headers (ヘッダーを公開)	プロキシのシナリオで、バックエンドへの要求でヘッダーを公開する必要があるかどうかを指定します。統合サーバーによって返されるユーザープロパティは、「X-AGW-」というプレフィックスが付けられ、ヘッダーとしてバックエンドに送信されます。	この要素についての詳細は、「Mule アプリケーションのトークン検証エンドポイント情報の活用」を参照してください。
Skip Client Id Validation (クライアント ID 検証をスキップ)	クライアントアプリケーションの API コントラクト検証をスキップします。	選択した場合、「ポリシーのしくみ」セクションの図のステップ 4 がスキップされます。
Authentication request timeout (認証要求タイムアウト)	アクセストークン検証エンドポイントを認証するときに、応答を待機する最大時間 (ミリ秒単位) を設定します。	`10000`

Scopes (スコープ)

サポートされるスコープのカンマ区切りリストを表示します。

READ, WRITE, READ and WRITE

Scope Validation Criteria (スコープ検証条件)

トークンに定義済みのすべてのスコープが含まれる必要があるか、1 つのみ含まれる必要があるかを決定します。この値は、Contains all scopes と Contains any scope です。

[Contains all scopes (すべてのスコープを含む)] 値が選択されている場合、スコープ READ と WRITE を持つトークンが受け入れられます。[Contains any scopes (任意のスコープを含む)] 値が選択されている場合、スコープ READ, WRITE, and READ AND WRITE を持つトークンが受け入れられます。

Validate TLS Certificate (TLS 証明書の検証) (Mule のみ)

サードパーティ認証サーバーの TLS 検証を有効にします。

選択した場合、トークン検証エンドポイントとの通信には TLS プロトコルが使用されます。

Expose Headers (ヘッダーを公開)

プロキシのシナリオで、バックエンドへの要求でヘッダーを公開する必要があるかどうかを指定します。統合サーバーによって返されるユーザープロパティは、「X-AGW-」というプレフィックスが付けられ、ヘッダーとしてバックエンドに送信されます。

この要素についての詳細は、「Mule アプリケーションのトークン検証エンドポイント情報の活用」を参照してください。

Skip Client Id Validation (クライアント ID 検証をスキップ)

クライアントアプリケーションの API コントラクト検証をスキップします。

選択した場合、「ポリシーのしくみ」セクションの図のステップ 4 がスキップされます。

Authentication request timeout (認証要求タイムアウト)

アクセストークン検証エンドポイントを認証するときに、応答を待機する最大時間 (ミリ秒単位) を設定します。

10000

非 Mule アプリケーションのパラメーターの設定 (Anypoint Service Mesh)

Anypoint Service Mesh によって管理される非 Mule アプリケーションの場合、次のパラメーターが表示されます。

要素説明例

要素	説明	例
Scopes (スコープ)	サポートされるスコープのカンマ区切りリストを表示します。	`READ`、`WRITE`、`READ AND WRITE`
Skip Client Id Validation (クライアント ID 検証をスキップ)	クライアントアプリケーションの API コントラクト検証をスキップします。	選択した場合、「ポリシーのしくみ」セクションの図のステップ 4 はスキップされます。

Scopes (スコープ)

サポートされるスコープのカンマ区切りリストを表示します。

READ、WRITE、READ AND WRITE

Skip Client Id Validation (クライアント ID 検証をスキップ)

クライアントアプリケーションの API コントラクト検証をスキップします。

選択した場合、「ポリシーのしくみ」セクションの図のステップ 4 はスキップされます。

ポリシーのしくみ

次の図は、OpenID Connect アクセストークン適用ポリシーワークフローを示しています。

OpenID Connect ポリシーを介して API とやり取りするユーザーのプロセスを示すフローチャート

この図には次の動作が示されています。

ユーザーが最初にポリシーで保護された API に HTTP 要求を送信します。
ポリシーは要求からトークンを抽出し、それを検証エンドポイントに送信して、トークンの整合性を検証します。
トークン検証エンドポイントは、クライアントアプリケーションのクライアント ID を含むトークンメタデータを返します。
ポリシーは Anypoint Platform から以前に取得したコントラクトで更新されたローカルデータベースを使用して、クライアント ID が API にアクセスできるかどうかを検証します。
すべての検証が正常に完了すると、要求はバックエンドに到達できます。

Mule アプリケーションのトークン検証エンドポイント情報の活用

トークン検証エンドポイントで正常にトークンが検証されると、特定の情報 (OpenID Connect の設定可能な項目など) がポリシーに返されます。

次の例は、認証サーバーからのトークン検証応答を示しています:

---
{
    "uid":"john.doe",
    "mail":"john.doe@example.com"
    "token_type":"Bearer",
    "exp": 1516239022
    "alias" : ["Jhon", "Jhonny", "Mr Doe"],
    "address" : {
        "city": "london",
        "road": “abbey road"
    }
}
---

OAuth プロバイダーによって返された項目はポリシーによって処理され、Mule フロー全体に伝播され、アクセスを要求しているアプリケーションが HTTP リクエスターを使用している場合は最終的にバックエンドに公開されます。

トークンキャッシュ

システムがトークンを検証すると、そのトークンは (デフォルトで) 期限切れになるまでキャッシュされるため、ポリシーのパフォーマンスが向上します。失効したトークンなどの特定のケースでは、キャッシュを最小限に抑えたり無効にしたりできます。

検証エンドポイントは、トークンの有効期限などの複数のプロパティをポリシーに送信します。有効期限情報がない場合、トークンはキャッシュされません。

トークンのキャッシュにかかる時間を制御するには、トークン検証エンドポイントに対して再検証を試みる前に、Engine でこの設定を行います。

Mule: Mule Runtime Engine を起動するときに次のプロパティを指定します。
```
`anypoint.platform.max_federation_expiration_time=<expiration time in seconds>`
```

または、wrapper.conf ファイルでこのパラメーターを指定できます。

Flex Gateway: YAML ポリシー設定ファイルでこのプロパティを指定します。

----
- policyRef:
    name: openidconnect-access-token-enforcement-flex
  config:
    ...
    maxFederationExpirationTime: <expiration time in seconds>
----

このプロパティを設定すると、指定された時間、またはトークンが期限切れになるまでのいずれか早い方でトークンがキャッシュされます。このプロパティが有効で、検証エンドポイントが有効期限情報を送信しない場合、トークンはキャッシュされません。

同時にキャッシュできるトークン数を制御するには、Engine で次の設定を行います。

Mule: Mule Runtime Engine を起動するときに次のプロパティを指定します。

`anypoint.platform.openid_connect_cache_max_size=<amount of tokens to be cached; default value is 10.000; specify 0 to disable caching>`

または、wrapper.conf ファイルでこのパラメーターを指定できます。

Flex Gateway: YAML ポリシー設定ファイルでこのプロパティを指定します。

----
 - policyRef:
    name: openidconnect-access-token-enforcement-flex
   config:
    ...
    maxCacheSize: <amount of tokens to be cached; default value is 1.000; specify 0 to disable caching>
----

トークン検証エンドポイント認証

指定されたトークンの検証が完了すると、ポリシーは要求を検証エンドポイントに送信します。次に、ポリシーは OAuth 2.0 認証フレームワーク仕様の「Token Introspection Client (トークンイントロスペクションクライアント)」セクションに従って、アクセス管理のクライアントプロバイダー設定からログイン情報を取得します。これらのログイン情報は、 OAuth 2.0 認証フレームワーク仕様の「Client Authentication (クライアント認証)」セクションで指定されているようにリクエストボディで送信されます。

トークン検証エンドポイントの認証方法は、現在サポートされていません。

Expose Headers (ヘッダーを公開) オプションの設定

ポリシーで Expose Headers オプションを設定し、アプリケーション (標準のプロキシなど) が HTTP リクエスターを使用している場合、プロパティはヘッダーとしてバックエンドにリダイレクトされます。

項目ごとに、元の保護されたリソースへの要求が「X-AGW- + <key>=<value>」形式を使用する HTTP ヘッダーで強化されます。前のセクションの応答例では、次のヘッダーが追加されています。

---
X-AGW-uid=john.doe
X-AGW-mail=john.doe@example.com
X-AGW-token_type=Bearer
---

伝播されたプロパティには、scope、exp オブジェクトおよび配列は含まれません。

フロー内の以降の処理では、検証エンドポイントからの元の解析していない応答を使用できます。情報は認証オブジェクトに保存されます。

たとえば、mail 項目がポリシーに返される場合、次の DataWeave 2.0 式を使用して項目の値にアクセスできます。

#[authentication.properties.userProperties.mail]

次の DataWeave 2.0 式を使用して、OAuth2 トークンのクライアント ID を取得できます。

#[authentication.principal]

プロキシを使用したトークン検証エンドポイントとの通信

OpenID Connect OAuth 2.0 トークン適用ポリシーでゲートウェイプロキシ設定を使用できるようにするには、Mule Runtime Engine の開始時に次のプロパティを指定します。

anypoint.platform.external_authentication_provider_enable_proxy_settings=<true|false(default)>

次のパラメーターを指定している場合、このプロパティを有効にすると、ポリシーは Mule プロキシ設定を使用します。

anypoint.platform.proxy_host=localhost
anypoint.platform.proxy_port=8080

FAQ

API に適用するポリシーのリストに OpenID Connect アクセストークン適用ポリシーが表示されない。

ポリシーリストにポリシーが表示されない場合、アクセス管理で OpenID クライアントプロバイダーを設定していることを確認します。詳細は、「OpenID Connect クライアント管理を設定する」を参照してください。複数のクライアントプロバイダーを使用している場合、API で OpenID Connect クライアントが正しく設定されていることを確認します。

ポリシーで OAuth 2.0 トークンを生成できますか?

いいえ。ポリシーはトークンの検証のみを行います。

Mule OAuth プロバイダー検証エンドポイントがポリシーによって送信された要求を拒否している場合はどうすればよいですか?

OpenID Connect サーバーから提供される検証エンドポイントドキュメントを参照し、「トークン検証エンドポイント認証」セクションに記載されている認証方法がサポートされているかどうかを確認します。

ポリシーは検証エンドポイントと通信するためのログイン情報をどのように管理しますか?

この情報は、ポリシー設定に含まれており、ディスクに保存されます。この情報を暗号化して保存する場合、ランタイムでゲートウェイ暗号化を設定します。

OAuth トークンはどのようにキャッシュされますか?

OAuth 2.0 トークンはメモリにのみキャッシュされ、ディスクに書き込まれることはありません。

ポリシーは要求ごとに Anypoint Platform と通信しますか?

いいえ。ポリシーは以前に Engine によって取得されたクライアントアプリケーションを使用します。これにより、管理プレーンとの接続が失われた場合でも、ポリシーが機能し続けます。ディスクに書き込まれるクライアントアプリケーション情報を暗号化する場合は、ランタイムでゲートウェイ暗号化を設定します。

OpenID Connect アクセストークン適用ポリシーを設定した後にレート制限 SLA ポリシーを設定できますか?

はい、できます。OpenID Connect アクセストークン適用ポリシーの後にレート制限 SLA ポリシーを適用し、次の DataWeave 2.0 式を使用して [Client ID Expression (クライアント ID 式)] の値を指定します。

#[authentication.principal]

リクエスターの ID はすでに OpenID Connect アクセストークン適用ポリシーで検証されているため、[Client Secret Expression (クライアントシークレット式)] 項目は空のままにできます。

トークンが検証された後に、トークンに関連付けられた情報をどこで確認できますか? この情報は認証オブジェクトにあります。詳細は、「Mule アプリケーションのトークン検証エンドポイント情報」を参照してください。