概要
アクセス トークン、更新トークン、認証コード、クライアント アプリ属性の属性を取得し、その値を変数に設定します。
このポリシーを使うと、トークンや認証コードの値に基づいて、条件付きの動的な動作を構成できます。トークンが検証されるたびに、トークン属性の値が自動的に変数へ設定されます。トークンが検証されていない場合は、この機能を使って、トークン属性の値を変数に設定できます。トークンと認証コードのカスタマイズもご覧ください。
このポリシーに渡すアクセス トークンを有効にする必要があります。有効でない場合、ポリシーで 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 |
ポリシーの内部名。 管理 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 ポリシーにより、この変数に値が設定されます。通常は、プロファイル データが必要だが、認可または検証がまだ行われていない場合に使用されます。
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>