SetOAuthV2Info ポリシー

概要

アクセス トークンに関連付けられたカスタム属性を追加または更新できます。カスタム属性としては、部門名、顧客 ID、セッション ID などを使用できます。トークンと認証コードのカスタマイズもご覧ください。

このポリシーを使用して追加または変更できるのは、カスタム属性のみです。scope、status、expires_in、developer_email、client_id、org_name、refresh_count などのフィールドをこのポリシーで変更することはできません。属性がすでに存在する場合、このポリシーによって更新されます。存在していなければ、このポリシーによって属性が追加されます。参照するアクセス トークンが有効であり、承認された状態になっている必要があります。

サンプル

基本的な例:

以下に、OAuth 2.0 アクセス トークンを更新するために使用するポリシーの例を示します。この例では、リクエスト メッセージでアクセス トークンを見つけるために、access_token という名前のクエリ パラメータを検索します。クライアント アプリがアクセス トークンを提示している場合、このポリシーはクエリ パラメータに含まれるアクセス トークンを特定し、そのアクセス トークンのプロファイルを更新します。department.id という名前のカスタム プロパティをプロファイルに追加します。

<SetOAuthV2Info name="SetOAuthV2Info">
  <AccessToken ref="request.queryparam.access_token"></AccessToken>
  <Attributes>
    <Attribute name="department.id" ref="request.queryparam.department_id"></Attribute>
  </Attributes>
</SetOAuthV2Info>

要素リファレンス

この要素リファレンスは、SetOAuthV2 ポリシーの要素と属性について説明しています。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SetOAuthV2Info async="false" continueOnError="false" enabled="true" name="SetOAuthV2Info-1">
    <DisplayName>Set OAuth v2.0 Info 1</DisplayName>
    <AccessToken ref={some-variable}></AccessToken>
    <Attributes/>
</SetOAuthV2Info>
</xml>

<SetOAuthV2Info> 属性

<SetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Set-OAuth-v20-Info-1">

次の表に、ポリシーのすべての親要素に共通の属性を記載します。

属性 説明 デフォルト 要否
name

ポリシーの内部名。name 属性の値には、文字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。255 文字を超える値を指定することはできません。

必要に応じて、管理 UI プロキシ エディタで <DisplayName> 要素を使用してポリシーに別のわかりやすい名前でラベルを付けます。

なし 必須
continueOnError

ポリシーが失敗した場合にエラーを返すには、false に設定します。これはほとんどのポリシーで想定される動作です。

ポリシーが失敗してもフロー実行を続行するには、true に設定します。

false 省略可
enabled

ポリシーを適用するには true に設定します。

ポリシーを無効にするには false に設定します。その場合、ポリシーはフローに接続されていているとしても適用されません。

true 省略可
async

この属性は非推奨となりました。

false 非推奨

<DisplayName> 要素

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。

<DisplayName>Policy Display Name</DisplayName>
デフォルト:

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます

要否: 省略可
型: 文字列

<AccessToken> 要素

アクセス トークンが格納される変数を識別する要素です。たとえば、アクセス トークンがクエリ パラメータとしてリクエスト メッセージにアタッチされている場合は、request.queryparam.access_token を指定します。トークンを参照する有効な変数を使用できます。まれなケースですが、リテラル トークン文字列を渡すこともできます。

 <AccessToken ref="request.queryparam.access_token"></AccessToken>
デフォルト: なし
要否: 必須
型: 文字列

属性

属性 説明 デフォルト 要否
ref

アクセス トークン変数。通常は、フロー変数から取得されます。

なし 省略可

<Attributes> 要素

変更または拡張される、アクセス トークン プロファイル内の一連の属性。

デフォルト: なし
要否: 必須
型: なし

<Attributes>/<Attribute> 要素

更新する個々の属性。

name 属性で、更新するアクセス トークンのカスタム プロパティを識別します。次の例に、参照先変数の値と静的な値を使用する方法を示します。

  <Attributes>
    <Attribute name="department.id" ref="request.queryparam.department_id"></Attribute>
    <Attribute name="foo">bar</Attribute>
  </Attributes>
デフォルト: なし
要否: 省略可
型: なし

属性

属性 説明 デフォルト 要否
name 追加または変更するプロファイル属性の名前。 なし
ref

プロファイル属性に割り当てる値。

なし 省略可

フロー変数

成功すると、次のフロー変数が設定されます。

  • oauthv2accesstoken.{policyName}.access_token
  • oauthv2accesstoken.{policyName}.client_id
  • oauthv2accesstoken.{policyName}.refresh_count
  • oauthv2accesstoken.{policyName}.organization_name
  • oauthv2accesstoken.{policyName}.expires_in //--in seconds
  • oauthv2accesstoken.{policyName}.refresh_token_expires_in //--in seconds
  • oauthv2accesstoken.{policyName}.issued_at
  • oauthv2accesstoken.{policyName}.status
  • oauthv2accesstoken.{policyName}.api_product_list
  • oauthv2accesstoken.{policyName}.token_type
  • oauthv2accesstoken.{policyName}.{custom_attribute_name}

スキーマ

各ポリシータイプは XML スキーマ(.xsd)で定義されています。GitHub に参照用のポリシー スキーマが用意されています。

エラー リファレンス

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause
steps.oauth.v2.access_token_expired 500 The access token sent to the policy is expired.
steps.oauth.v2.invalid_access_token 500 The access token sent to the policy is invalid.
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401 Please see this Apigee Community post for information about troubleshooting this error.

Deployment errors

Refer to the message reported in the UI for information about deployment errors.

Fault variables

These variables are set when this policy triggers an error at runtime.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "invalid_access_token"
oauthV2.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. oauthV2.SetTokenInfo.failed = true
oauthV2.policy_name.fault.name policy_name is the user-specified name of the policy that threw the fault. oauthV2.SetTokenInfo.fault.name = invalid_access_token
oauthv2.policy_name.fault.cause policy_name is the user-specified name of the policy that threw the fault. oauthV2.SetTokenInfo.cause = Invalid Access Token

Example error response

{
  "fault": {
    "faultstring": "Invalid Access Token",
    "detail": {
      "errorcode": "keymanagement.service.invalid_access_token"
    }
  }
}

Example fault rule

<FaultRule name=SetOAuthV2Info Faults">
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

関連トピック