GetOAuthV2Info ポリシー

概要

アクセス トークン、リフレッシュ トークン、認可コード、クライアント アプリ属性の属性を取得し、その値を変数に設定します。

このポリシーを使うと、トークンや認可コードの値に基づいて、条件付きの動的な動作を構成できます。トークンが検証されるたびに、トークン属性の値が自動的に変数へ設定されます。トークンが検証されていない場合は、この機能を使って、トークン属性の値を変数に設定できます。詳しくは、トークンと認可コードのカスタマイズをご覧ください。

このポリシーに渡すアクセス トークンが不正の場合、ポリシーにより invalid_access_token エラーがスローされます。

サンプル

以下のサンプルでは、Get OAuth V2 Info ポリシーを使って、OAuth2 ワークフローのさまざまなコンポーネントに関する情報を取得し、その情報にコードからアクセスします。

アクセス トークン

アクセス トークンへの参照を取得するには、ポリシー内の <AccessToken> 要素を使います。

次の例では、「access_token」という名前のクエリ パラメータでアクセス トークンを検索します(実装する際の詳細は必要に応じて決定します)。

<GetOAuthV2Info name="MyTokenAttrsPolicy">
      <AccessToken ref="request.queryparam.access_token"></AccessToken>
    </GetOAuthV2Info>
    

アクセス トークンが与えられると、ポリシーはトークンのプロファイルを検索し、プロファイルのデータを一連の変数に設定します。

こうすると、JavaScript やその他の手段で、この変数にアクセスできるようになります。次の例では、JavaScript でアクセス トークンに関連付けられたスコープを取得します。

var scope = context.getVariable('oauthv2accesstoken.MyTokenAttrsPolicy.scope');

これらの変数にコードからアクセスするには、接頭辞「oauthv2accesstoken」を付ける必要があります。アクセス トークンを使ってアクセスできる変数の完全なリストについては、アクセス トークン変数をご覧ください。

認可コード

認可コード属性を取得するには、ポリシーの <AuthorizationCode> 要素を使います。

次の例では、「code」という名前のフォーム パラメータでアクセス トークンを検索します(実装する際の詳細は必要に応じて決定します)。

<GetOAuthV2Info name="MyAuthCodeAttrsPolicy">
      <AuthorizationCode ref="request.formparam.code"></AuthorizationCode>
    </GetOAuthV2Info>

認可コードが与えられると、ポリシーはコードの情報を検索し、認可コードのデータを一連の変数に設定します。

こうすると、JavaScript やその他の手段で、この変数にアクセスできるようになります。次の例では、JavaScript で認可コードに関連付けられたカスタム属性を取得します。

var attr = context.getVariable(‘oauthv2authcode.MyAuthCodeAttrsPolicy.custom_attribute_name’);

これらの変数にコードからアクセスするには、接頭辞「oauthv2authcode」を付ける必要があります。認可コードを使ってアクセスできる変数の完全なリストについては、認可コード変数をご覧ください。

リフレッシュ トークン

リフレッシュ トークン属性を取得するには、ポリシーの <RefreshToken> 要素を使います。

次の例では、「refresh_token」という名前のクエリ パラメータでアクセス トークンを検索します(実装する際の詳細は必要に応じて決定します)。

<GetOAuthV2Info name="MyRefreshTokenAttrsPolicy">
      <RefreshToken ref="request.queryparam.refresh_token"/>
    </GetOAuthV2Info>

リフレッシュ トークンが与えられると、ポリシーはリフレッシュ トークンの情報を検索し、リフレッシュ トークンのデータを一連の変数に設定します。

こうすると、JavaScript やその他の手段で、この変数にアクセスできるようになります。次の例では、JavaScript でリフレッシュ トークンに関連付けられたカスタム属性を取得します。

var attr = context.getVariable(‘oauthv2refreshtoken.MyRefreshTokenAttrsPolicy.accesstoken.custom_attribute_name’);

これらの変数にコードからアクセスするには、接頭辞「oauthv2refreshtoken」を付ける必要があります。リフレッシュ トークンを使ってアクセスできる変数の完全なリストについては、リフレッシュ トークン変数をご覧ください。

静的

まれに、静的に構成されたトークン(変数を使用してアクセスできないトークン)のプロファイルを取得する必要がある場合があります。これは、要素としてアクセス トークンの値を指定すれば可能です。

    <GetOAuthV2Info name="GetTokenAttributes">
      <AccessToken>shTUmeI1geSKin0TODcGLXBNe9vp</AccessToken>
    </GetOAuthV2Info>
    

これは他のすべてのトークンタイプ(クライアント ID、認可コード、リフレッシュ トークン)でも可能です。

クライアント ID

この例では、クライアント ID を使用してクライアント アプリに関する情報を取得する方法を示します。これを実行すると、ポリシーがクライアント情報を一連の変数に設定します。この例では、ポリシーは client_id というクエリ パラメータでクライアント ID を見つけることを想定しています。クライアント ID が与えられると、ポリシーはクライアントのプロファイルを検索し、プロファイルのデータを一連の変数に設定します。この変数には接頭辞 oauthv2client. が付きます。

    <GetOAuthV2Info name="GetClientAttributes">
      <ClientId ref="request.queryparam.client_id"></ClientId>
    </GetOAuthV2Info>
    

こうすると、JavaScript やその他の手段で、この変数にアクセスできるようになります。次の例では、JavaScript を使用してクライアント アプリに関連付けられているデベロッパーのアプリ名とデベロッパーのメールアドレスを取得します。

    context.getVariable("oauthv2client.GetClientAttributes.developer.email");
    context.getVariable("oauthv2client.GetClientAttributes.developer.app.name");
    

要素リファレンス

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

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="GetOAuthV2Info-1"
        <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
        <AccessToken ref="variable"></AccessToken>
        <AuthorizationCode ref="variable"></AuthorizationCode>
        <ClientId ref="variable"></ClientId>
        <RefreshToken ref="variable"></RefreshToken>
    </GetOAuthV2Info
    

<GetOAuthV2Info> の属性

    <GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Get-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> 要素

アクセス トークンのプロファイルを取得します。アクセス トークン文字列またはリテラルのトークン文字列(まれなケース)のどちらかが入った変数を渡します。次の例では、リクエストで渡されたクエリ パラメータからアクセス トークンを取得します。失効または期限切れのトークンに関する情報を返す場合は、<IgnoreAccessTokenStatus> 要素を使用します。

    <AccessToken ref="request.queryparam.access_token"></AccessToken>
    

デフォルト:

request.formparam.access_token(x-www-form-urlencoded、リクエスト本文で指定)

要否:

省略可

型: 文字列
有効な値:

アクセス トークン文字列が入ったフロー変数、またはリテラル文字列のどちらか


<AuthorizationCode> 要素

認可コードのプロファイルを取得します。認可コード文字列またはリテラルのトークン文字列(まれなケース)のどちらかが入った変数を渡します。次の例では、リクエストで渡されたクエリ パラメータから認可コードを取得します。この操作で設定される変数の完全なリストについては、フロー変数をご覧ください。

    <AuthorizationCode ref="request.queryparam.authorization_code"></AuthorizationCode>
    

デフォルト:

request.formparam.access_token(x-www-form-urlencoded、リクエスト本文で指定)

要否:

省略可

型: 文字列
有効な値:

認可コード文字列が入ったフロー変数、またはリテラル文字列のどちらか

<ClientId> 要素

クライアント ID に関連した情報取得します。次の例では、リクエストで渡されたクエリ パラメータからクライアント ID を取得します。この操作で設定される変数の完全なリストについては、フロー変数をご覧ください。

    <ClientId ref="request.queryparam.client_id"></ClientId>
    

デフォルト:

request.formparam.access_token(x-www-form-urlencoded、リクエスト本文で指定)

要否:

省略可

型: 文字列
有効な値: 認可コード文字列が入ったフロー変数、またはリテラル文字列のどちらか

<IgnoreAccessTokenStatus> 要素

トークンが期限切れまたは失効の場合でも、トークン情報を返します。この要素は、アクセス トークンでのみ使用できます。リフレッシュ トークンや認可コードなどの他のエンティティの情報は、デフォルトで、ステータスに関係なく返されます。

    <IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>
    

デフォルト:

false

必須?:

省略可

型: ブール値
有効な値: true または false

<RefreshToken> 要素

リフレッシュ トークンのプロファイルを取得します。リフレッシュ トークン文字列またはリテラルのトークン文字列(まれなケース)のどちらかが入った変数を渡します。次の例では、リクエストで渡されたクエリ パラメータからリフレッシュ トークンを取得します。この操作で設定される変数の完全なリストについては、フロー変数をご覧ください。

    <RefreshToken ref="request.queryparam.refresh_token"></RefreshToken>
    

デフォルト:

request.formparam.access_token(x-www-form-urlencoded、リクエスト本文で指定)

要否:

省略可

型: 文字列
有効な値:

リフレッシュ トークン文字列が入ったフロー変数、またはリテラル文字列のどちらか

フロー変数

GetOAuthV2Info ポリシーにより、この変数に値が設定されます。通常は、プロファイル データが必要だが、認可または検証がまだ行われていない場合に使用されます。

Client ID 変数

ClientId 要素が設定されると、以下の変数に値が設定されます。

    oauthv2client.{policy_name}.client_id
    oauthv2client.{policy_name}.client_secret
    oauthv2client.{policy_name}.redirection_uris // Note the spelling -- 'redirection_uris'
    oauthv2client.{policy_name}.developer.email
    oauthv2client.{policy_name}.developer.app.name
    oauthv2client.{policy_name}.developer.id
    oauthv2client.{policy_name}.{developer_app_custom_attribute_name}
    

アクセス トークン変数

AccessToken 要素が設定されると、以下の変数に値が設定されます。

    oauthv2accesstoken.{policy_name}.developer.id
    oauthv2accesstoken.{policy_name}.developer.app.name
    oauthv2accesstoken.{policy_name}.developer.app.id
    oauthv2accesstoken.{policy_name}.developer.email

    oauthv2accesstoken.{policy_name}.organization_name
    oauthv2accesstoken.{policy_name}.api_product_list

    oauthv2accesstoken.{policy_name}.access_token
    oauthv2accesstoken.{policy_name}.scope
    oauthv2accesstoken.{policy_name}.expires_in //in seconds
    oauthv2accesstoken.{policy_name}.status
    oauthv2accesstoken.{policy_name}.client_id
    oauthv2accesstoken.{policy_name}.accesstoken.{custom_attribute_name}

    oauthv2accesstoken.{policy_name}.refresh_token
    oauthv2accesstoken.{policy_name}.refresh_token_status
    oauthv2accesstoken.{policy_name}.refresh_token_expires_in //in seconds

    oauthv2accesstoken.{policy_name}.refresh_count
    oauthv2accesstoken.{policy_name}.refresh_token_issued_at
    

認可コード変数

AuthorizationCode 要素が設定されると、以下の変数に値が設定されます。

    oauthv2authcode.{policy_name}.code
    oauthv2authcode.{policy_name}.scope
    oauthv2authcode.{policy_name}.redirect_uri
    oauthv2authcode.{policy_name}.client_id
    oauthv2authcode.{policy_name}.{auth_code_custom_attribute_name}
    

リフレッシュ トークン変数

RefreshToken 要素が設定されると、以下の変数に値が設定されます。

    oauthv2refreshtoken.{policy_name}.developer.id
    oauthv2refreshtoken.{policy_name}.developer.app.name
    oauthv2refreshtoken.{policy_name}.developer.app.id
    oauthv2refreshtoken.{policy_name}.developer.email
    oauthv2refreshtoken.{policy_name}.organization_name
    oauthv2refreshtoken.{policy_name}.api_product_list

    oauthv2refreshtoken.{policy_name}.access_token
    oauthv2refreshtoken.{policy_name}.scope
    oauthv2refreshtoken.{policy_name}.expires_in //in seconds

    oauthv2refreshtoken.{policy_name}.status
    oauthv2refreshtoken.{policy_name}.client_id
    oauthv2refreshtoken.{policy_name}.accesstoken.{custom_attribute_name}

    oauthv2refreshtoken.{policy_name}.refresh_token
    oauthv2refreshtoken.{policy_name}.refresh_token_status
    oauthv2refreshtoken.{policy_name}.refresh_token_expires_in //in seconds

    oauthv2refreshtoken.{policy_name}.refresh_count
    oauthv2refreshtoken.{policy_name}.refresh_token_issued_at
    

スキーマ

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

エラー リファレンス

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

ランタイム エラー

以下のエラーは、ポリシー実行時に発生する可能性があるものです。下記のエラー名は、エラー発生時に fault.name 変数に設定される文字列です。詳細については、下記の Fault 変数のセクションをご覧ください。

障害コード HTTP ステータス 原因
steps.oauth.v2.access_token_expired 500 ポリシーに送信されたアクセス トークンは期限切れです。
steps.oauth.v2.authorization_code_expired 500 ポリシーに送信された認可コードは期限切れです。
steps.oauth.v2.invalid_access_token 500 ポリシーに送信されたアクセス トークンは無効です。
steps.oauth.v2.invalid_client-invalid_client_id 500 ポリシーに送信されたクライアント ID は無効です。
steps.oauth.v2.invalid_refresh_token 500 ポリシーに送信されたリフレッシュ トークンは無効です。
steps.oauth.v2.invalid_request-authorization_code_invalid 500 ポリシーに送信された認可コードは無効です。
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401 このエラーの解決方法については、Apigee コミュニティの投稿をご覧ください。
steps.oauth.v2.refresh_token_expired 500 ポリシーに送信されたリフレッシュ トークンは期限切れです。

デプロイエラー

デプロイエラーについては、UI に表示されたメッセージをご覧ください。

障害変数

以下の変数は、このポリシーにより実行時にエラーが発生したときに設定されます。

変数 説明
fault.name="fault_name" fault_name は、上記のランタイム エラー表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。 fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed policy_name は、障害をスローしたポリシーにユーザーが指定した名前です。 oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name policy_name は、障害をスローしたポリシーにユーザーが指定した名前です。 oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause policy_name は、障害をスローしたポリシーにユーザーが指定した名前です。 oauthV2.GetTokenInfo.cause = ClientID is Invalid

エラー レスポンスの例

    {  
       "fault":{  
          "faultstring":"ClientId is Invalid",
          "detail":{  
             "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
          }
       }
    }
    

障害ルールの例

    <FaultRule name="OAuthV2 Faults">
        <Step>
            <Name>AM-InvalidClientIdResponse</Name>
        </Step>
        <Condition>(fault.name = "invalid_client-invalid_client_id")</Condition>
    </FaultRule>
    

関連トピック