このページの内容は 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 |
ポリシーの内部名。 管理 UI プロキシ エディタで |
なし | 必須 |
continueOnError |
ポリシーが失敗したときにエラーを返す場合は、 ポリシーが失敗した後もフローの実行を続行する場合は、 |
false | 省略可 |
enabled |
ポリシーを適用するには、 ポリシーを無効にするには、 |
true | 省略可 |
async |
この属性は非推奨となりました。 |
false | 非推奨 |
<DisplayName> 要素
管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。
<DisplayName>Policy Display Name</DisplayName>
| デフォルト |
なし この要素を省略した場合、ポリシーの |
|---|---|
| 要否 | 省略可 |
| タイプ | 文字列 |
<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 から入手できます。
エラー リファレンス
This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes. The error names shown below are the strings
that are assigned to the fault.name variable when an error occurs. See the Fault
variables section below for more details.
| Fault code | HTTP status | Cause |
|---|---|---|
steps.oauth.v2.access_token_expired |
500 |
The access token sent to the policy is expired. |
steps.oauth.v2.authorization_code_expired |
500 |
The authorization code sent to the policy is expired. |
steps.oauth.v2.invalid_access_token |
500 |
The access token sent to the policy is invalid. |
steps.oauth.v2.invalid_client-invalid_client_id |
500 |
The client ID sent to the policy is invalid. |
steps.oauth.v2.invalid_refresh_token |
500 |
The refresh token sent to the policy is invalid. |
steps.oauth.v2.invalid_request-authorization_code_invalid |
500 |
The authorization code sent to the policy is invalid. |
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound |
401 | Please see Oauth2.0 Access Token Verification throws "Invalid API call as no apiproduct match found" error for information about troubleshooting this error. |
steps.oauth.v2.refresh_token_expired |
500 |
The refresh token sent to the policy is expired. |
Deployment errors
Refer to the message reported in the UI for information about deployment errors.
Fault variables
These variables are set when this policy triggers an error at runtime.
| Variables | Where | Example |
|---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name Matches "IPDeniedAccess" |
oauthV2.policy_name.failed |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.GetTokenInfo.failed = true |
oauthV2.policy_name.fault.name |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id |
oauthV2.policy_name.fault.cause |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.GetTokenInfo.cause = ClientID is Invalid |
Example error response
{ "fault":{ "faultstring":"ClientId is Invalid", "detail":{ "errorcode":"keymanagement.service.invalid_client-invalid_client_id" } } }
Example fault rule
<FaultRule name="OAuthV2 Faults">
<Step>
<Name>AM-InvalidClientIdResponse</Name>
</Step>
<Condition>(fault.name = "invalid_client-invalid_client_id")</Condition>
</FaultRule>