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

ポリシー名

OpenID Connect OAuth 2.0 トークン適用

概要

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

カテゴリ

セキュリティ

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

v1.0.0

返される状況コード

400 - 無効なトークン

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

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

500 - 認証サーバーからの不正応答

概要

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

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

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

Flex Gateway のローカルモード

ローカルモードでは、宣言型の設定ファイルを使用してポリシーを API に適用します。以下のポリシー定義とパラメーターの表を参照してください。

- policyRef:
    name: openidconnect-access-token-enforcement-flex
  config:
    authenticationTimeout: <int> // OPTIONAL, default: 10000
    scopes: <string> // OPTIONAL, default: ""
    secureTrustStore: <bool> // OPTIONAL, default: false
    scopeValidationCriteria: <string> // OPTIONAL, default: "AND"
    exposeHeaders: <bool> // OPTIONAL, default: false
    skipClientIdValidation: <bool> // OPTIONAL, default: true
    maxFederationExpirationTime: <int> // OPTIONAL, default: -1
    maxCacheSize: <int> // OPTIONAL, default: 1000

パラメーター必須または省略可能デフォルト値説明

パラメーター	必須または省略可能	デフォルト値	説明
`authenticationTimeout`	省略可能	10000
`scopes`	省略可能	空の文字列	サポートされるスコープのスペース区切りリスト: `read` `write`
`secureTrustStore`	省略可能	`false`
`scopeValidationCriteria`	省略可能	"AND"	トークンに定義済みのすべてのスコープが含まれる必要があるか、1 つのみ含まれる必要があるかを決定します。
`exposeHeaders`	省略可能	`false`	プロキシのシナリオで、バックエンドへの要求でヘッダーを公開する必要があるかどうかを指定します。統合サーバーによって返されるユーザープロパティは、「X-AGW-」というプレフィックスが付けられ、ヘッダーとしてバックエンドに送信されます。このパラメーターについての詳細は、「トークン検証エンドポイント情報の活用」を参照してください。
`skipClientIdValidation`	省略可能	`true`	クライアントアプリケーションの API コントラクト検証をスキップします。`true` の場合、「ポリシーのしくみ」セクションの図のステップ 4 がスキップされます。
`maxFederationExpirationTime`	省略可能	-1	最大有効期限 (秒)。このパラメーターの詳細は、「トークンキャッシュ」を参照してください。
`maxCacheSize`	省略可能	1000	キャッシュするトークンの数。このパラメーターの詳細は、「トークンキャッシュ」を参照してください。

authenticationTimeout

省略可能

10000

scopes

省略可能

空の文字列

サポートされるスコープのスペース区切りリスト: read write

secureTrustStore

省略可能

false

scopeValidationCriteria

省略可能

"AND"

トークンに定義済みのすべてのスコープが含まれる必要があるか、1 つのみ含まれる必要があるかを決定します。

exposeHeaders

省略可能

false

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

このパラメーターについての詳細は、「トークン検証エンドポイント情報の活用」を参照してください。

skipClientIdValidation

省略可能

true

クライアントアプリケーションの API コントラクト検証をスキップします。true の場合、「ポリシーのしくみ」セクションの図のステップ 4 がスキップされます。

maxFederationExpirationTime

省略可能

-1

最大有効期限 (秒)。

このパラメーターの詳細は、「トークンキャッシュ」を参照してください。

maxCacheSize

省略可能

1000

キャッシュするトークンの数。

このパラメーターの詳細は、「トークンキャッシュ」を参照してください。

リソースの設定例

- policyRef:
    name: openidconnect-access-token-enforcement-flex
  config:
    authenticationTimeout: 10000
    scopes: read write
    secureTrustStore: false
    scopeValidationCriteria: OR
    exposeHeaders: true
    skipClientIdValidation: false

管理 Flex Gateway および Flex Gateway の接続モード

UI からポリシーを API インスタンスに適用するときに、以下のパラメーターが表示されます。

要素説明例

要素	説明	例
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` を持つトークンが受け入れられます。
Expose Headers (ヘッダーを公開)	プロキシのシナリオで、バックエンドへの要求でヘッダーを公開する必要があるかどうかを指定します。統合サーバーによって返されるユーザープロパティは、「X-AGW-」というプレフィックスが付けられ、ヘッダーとしてバックエンドに送信されます。
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 を持つトークンが受け入れられます。

Expose Headers (ヘッダーを公開)

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

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

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

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

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

10000

ポリシーのしくみ

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

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

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

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

トークン検証エンドポイント情報の活用

トークン検証エンドポイントで正常にトークンが検証されると、特定の情報 (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 プロバイダーによって返された項目はポリシーによって処理され、フロー全体に伝播され、アクセスを要求しているアプリケーションが HTTP リクエスターを使用している場合は最終的にバックエンドに公開されます。

ローカルモードでのトークンキャッシュ

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

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

トークンのキャッシュにかかる時間を制御するには、トークン検証エンドポイントに対して再検証を試みる前に、宣言型設定ファイルで次のパラメーターを設定します。

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

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

同時にキャッシュできるトークンの数を制御するには、宣言型設定ファイルで次のパラメーターを設定します。

  - 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]

FAQ

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

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

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

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

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

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

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

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

#[authentication.principal]

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