SetOAuthV2Info ポリシー

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

概要

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

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

このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

サンプル

基本的な例

以下に、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">

The following table describes attributes that are common to all policy parent elements:

Attribute	Description	Default	Presence
`name`	The internal name of the policy. The value of the `name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the `<DisplayName>` element to label the policy in the management UI proxy editor with a different, natural-language name.	N/A	Required
`continueOnError`	Set to `false` to return an error when a policy fails. This is expected behavior for most policies. Set to `true` to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	false	Optional
`enabled`	Set to `true` to enforce the policy. Set to `false` to turn off the policy. The policy will not be enforced even if it remains attached to a flow.	true	Optional
`async`	This attribute is deprecated.	false	Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

Default

Default	N/A If you omit this element, the value of the policy's `name` attribute is used.
Presence	Optional
Type	String

N/A

If you omit this element, the value of the policy's name attribute is used.

Presence Optional

Type String

<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 Apigee 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 Oauth2.0 Access Token Verification throws "Invalid API call as no apiproduct match found" error 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>