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">

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.	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> 要素

アクセストークンのプロファイルを取得します。アクセストークン文字列またはリテラルのトークン文字列（まれなケース）のどちらかが入った変数を渡します。次の例では、アクセストークンはリクエストで渡されたクエリパラメータから取得されます。失効または期限切れのトークンに関する情報を返す場合は、<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
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 から入手できます。

エラーリファレンス

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

ランタイムエラー

このエラーは、ポリシーの実行時に発生することがあります。以下のエラー名は、エラーが発生したときに 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	このエラーのトラブルシューティングについては、こちらの 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>