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	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 から入手できます。

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード	HTTP ステータス	原因
steps.oauth.v2.access_token_expired	500	ポリシーに送信されたアクセス トークンが期限切れになっています。
steps.oauth.v2.invalid_access_token	500	ポリシーに送信されたアクセス トークンが無効です。
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound	401	このエラーのトラブルシューティングについては、Oauth2.0 Access Token Verification throws "Invalid API call as no apiproduct match found" error をご覧ください。

デプロイエラー

デプロイエラーについては、UI で報告されるメッセージを参照してください。

障害変数

次の変数は、このポリシーでランタイム エラーが発生したときに設定されます。

注: これらの変数を使用して障害ルール条件を作成できます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

変数	説明	例
fault.name="fault_name"	fault_name は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。	fault.name = "invalid_access_token"
oauthV2.policy_name.failed	policy_name は、障害が発生したポリシーのユーザー指定の名前です。	oauthV2.SetTokenInfo.failed = true
oauthV2.policy_name.fault.name	policy_name は、障害が発生したポリシーのユーザー指定の名前です。	oauthV2.SetTokenInfo.fault.name = invalid_access_token
oauthv2.policy_name.fault.cause	policy_name は、障害が発生したポリシーのユーザー指定の名前です。	oauthV2.SetTokenInfo.cause = Invalid Access Token

エラー レスポンスの例

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

障害ルールの例

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

関連トピック

• OAuthV2 ポリシー
• OAuth ホーム
• トークンと認証コードのカスタマイズ