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>
    
デフォルト: なし
必須?: 必須
型: String

属性

属性 説明 デフォルト 要否
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 に参照用のポリシー スキーマが用意されています。

エラー リファレンス

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

ランタイム エラー

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

障害コード HTTP ステータス 原因
steps.oauth.v2.access_token_expired 500 ポリシーに送信されたアクセス トークンは期限切れです。
steps.oauth.v2.invalid_access_token 500 ポリシーに送信されたアクセス トークンは無効です。
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401 このエラーのトラブルシューティングについては、Apigee コミュニティの投稿をご覧ください。

デプロイエラー

デプロイエラーについては、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>
    

関連トピック