GetOAuthV2Info ポリシー

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

Apigee Edge のドキュメントはこちらをご覧ください。

ポリシー アイコン

内容

アクセス トークン、更新トークン、認証コード属性、クライアント アプリ属性を取得し、それらの属性値を変数に設定します。

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

このポリシーに渡すアクセス トークンを有効にする必要があります。有効でない場合、ポリシーで invalid_access_token エラーがスローされます。

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

サンプル

以下のサンプルでは、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> 要素

管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

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

クライアント 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
oauthv2accesstoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

認証コード変数

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
oauthv2refreshtoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

スキーマ

各ポリシータイプは XML スキーマ（.xsd）によって定義されます。参照用のポリシー スキーマは GitHub から入手できます。

エラー リファレンス

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

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。以下のエラー名は、エラーが発生したときに fault.name 変数に割り当てられる文字列です。詳細については、以下の障害変数のセクションをご覧ください。

障害コード 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 このエラーのトラブルシューティングについては、Oauth2.0 Access Token Verification throws "Invalid API call as no apiproduct match found" error をご覧ください。
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>

関連トピック