OAuth V2 ポリシーを取り消す

このページは Apigee と Apigee ハイブリッドに適用されます。

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

概要

デベロッパーアプリ ID またはアプリのエンドユーザー ID または両方に関連付けられた OAuth2 アクセストークンを取り消します。

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

OAuthv2 ポリシーを使用して、OAuth 2.0 アクセストークンを生成します。Apigee で生成されるトークンの形式は次のとおりです。

{
  "issued_at" : "1421847736581",
  "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
  "scope" : "READ",
  "status" : "approved",
  "api_product_list" : "[PremiumWeatherAPI]",
  "expires_in" : "3599", //--in seconds
  "developer.email" : "tesla@weathersample.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
  "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
  "organization_name" : "myorg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

application_name 要素には、トークンに関連付けられているデベロッパーアプリ ID が含まれます。

デフォルトでは、Apigee のトークンにエンドユーザー ID が含まれません。エンドユーザー ID が含まれるように Apigee を構成するには、<AppEndUser> 要素を OAuthv2 ポリシーに追加します。

<OAuthV2 name="GenerateAccessTokenClient">
    <Operation>GenerateAccessToken</Operation>
    ...
    <AppEndUser>request.queryparam.app_enduser</AppEndUser>
</OAuthV2>

この例では、エンドユーザー ID を app_enduser という名前のクエリパラメータの OAuthv2 ポリシーに渡しています。こうすることで、エンドユーザー ID は、app_enduser 要素のトークンに含まれるようになります。

{
 "issued_at" : "1421847736581",
 "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
 "scope" : "READ",
 "app_enduser" : "6ZG094fgnjNf02EK",
 "status" : "approved",
 "api_product_list" : "[PremiumWeatherAPI]",
 "expires_in" : "3599", //--in seconds
 "developer.email" : "tesla@weathersample.com",
 "organization_id" : "0",
 "token_type" : "BearerToken",
 "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
 "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
 "organization_name" : "myorg",
 "refresh_token_expires_in" : "0", //--in seconds
 "refresh_count" : "0"
}

デベロッパーアプリ ID により取り消す

デベロッパーアプリ ID に関連付けられた OAuth2 アクセストークンを取り消します。 Apigee によって生成されたすべての OAuth2 アクセストークンには、そのトークンに関連付けられているデベロッパーアプリの ID が含まれます。そのため、そのアプリ ID に基づいてトークンを取り消すことができます。

特定のデベロッパーのアプリ ID のリストを取得するには、以下を使用します。

メソッド: organizations.developers.apps.list デベロッパーに関連付けられているアプリのリストを取得できる API。
メソッド: organizations.developers.apps.get アプリ ID を含むアプリの詳細を取得できる API。

アプリエンドユーザー ID により取り消す

特定のアプリのエンドユーザー ID に関連付けられた OAuth2 アクセストークンを取り消します。これは、トークンが発行されたユーザーの ID に関連付けられたトークンです。

デフォルトでは、OAuth アクセストークンにはエンドユーザー ID のフィールドはありません。エンドユーザー ID により OAuth 2.0 アクセストークンを取り消せるようにするには、上記で説明するように、OAuthv2 ポリシーを構成してトークンにユーザー ID を組み込む必要があります。

アプリのエンドユーザー ID を取得するには、メソッド: organizations.developers.get を使用します。

サンプル

以下のサンプルでは、Revoke OAuth V2 ポリシーを使用して、OAuth2 アクセストークンを取り消しています。

デベロッパーアプリ ID

デベロッパーアプリ ID でアクセストークンを取り消すには、ポリシーで <AppId> 要素を使用します。

次の例では、app_id というクエリパラメータで、アクセストークンのデベロッパーアプリ ID を検索します。

<RevokeOAuthV2 continueOnError="false" enabled="true" name="MyRevokeTokenPolicy">
  <DisplayName>Revoke OAuth v2.0-1</DisplayName>
  <AppId ref="request.queryparam.app_id"></AppId>
</RevokeOAuthV2>

デベロッパーアプリの ID を指定すると、ポリシーによってアクセストークンが取り消されます。

タイムスタンプより前を指定して取り消す

デベロッパーアプリ ID によって、特定の日時より前に生成されたアクセストークンを取り消すには、ポリシーで <RevokeBeforeTimestamp> 要素を使用します。<RevokeBeforeTimestamp> は、UTC エポック時間をミリ秒単位で指定します。この時間より前に発行されたトークンはすべて取り消されます。

次の例では、2019 年 7 月 1 日より前に作成されたデベロッパーアプリのアクセストークンを取り消します。

<RevokeOAuthV2 continueOnError="false" enabled="true" name="MyRevokeTokenPolicy">
  <DisplayName>Revoke OAuth v2.0-1</DisplayName>
  <AppId ref="request.queryparam.app_id"></AppId>
  <RevokeBeforeTimestamp>1561939200000</RevokeBeforeTimestamp>
</RevokeOAuthV2>

<RevokeBeforeTimestamp> 要素は、1970 年 1 月 1 日午前 0 時（UTC）からの経過時間（ミリ秒）を表す 64 ビット（long 型）の整数の値を取ります。

要素リファレンス

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RevokeOAuthV2 continueOnError="false" enabled="true" name="GetOAuthV2Info-1">
  <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
  <AppId ref="variable"></AppId>
  <EndUserId ref="variable"></EndUserId>
  <RevokeBeforeTimestamp ref="variable"></RevokeBeforeTimestamp>
  <Cascade>false</Cascade>
</RevokeOAuthV2>

<RevokeOAuthV2> 属性

<RevokeOAuthV2 continueOnError="false" enabled="true" name="Revoke-OAuth-v20-1">

次の表に、すべてのポリシーの親要素に共通する属性を示します。

属性説明デフォルト要否

属性	説明	デフォルト	要否
`name`	ポリシーの内部名。`name` 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。管理 UI プロキシエディタで `<DisplayName>` 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。	なし	必須
`continueOnError`	ポリシーが失敗したときにエラーを返す場合は、`false` に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、`true` に設定します。	false	省略可
`enabled`	ポリシーを適用するには、`true` に設定します。ポリシーを無効にするには、`false` に設定します。ポリシーがフローに接続されている場合でも適用されません。	true	省略可

name

ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。

管理 UI プロキシエディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。

なし

必須

continueOnError

ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。

ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。

false

省略可

enabled

ポリシーを適用するには、true に設定します。

ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。

true

省略可

<DisplayName> 要素

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

<DisplayName>Policy Display Name</DisplayName>

デフォルト

デフォルト	なしこの要素を省略した場合、ポリシーの `name` 属性の値が使用されます。
要否	省略可
タイプ	文字列

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます。

要否省略可

タイプ文字列

<AppId> 要素

取り消すトークンのデベロッパーアプリ ID を指定します。アプリ ID を格納する変数またはリテラルのアプリ ID を渡します。

<AppId>appIdString</AppId>

or:

<AppId ref="request.queryparam.app_id"></AppId>

デフォルト	`request.formparam.app_id`（x-www-form-urlencoded、リクエスト本文で指定）
プレゼンス	省略可
タイプ	文字列
有効な値	アプリ ID 文字列を含むフロー変数、またはリテラル文字列のどちらか

<Cascade> 要素

true であり、従来の不透明アクセストークンがある場合、<AppId> または <EndUserId> のいずれかが一致すると、更新トークンとアクセストークンの両方が取り消されます。JWT アクセストークンがある場合、アクセストークンで発行された更新トークンのみが取り消されます。設計上、JWT アクセストークンを取り消すことはできません。false の場合、アクセストークンのみが取り消され、更新トークンは変更されません。不透明アクセストークンにも同じ動作が適用されます。JWT アクセストークンを取り消すことはできません。

<Cascade>false<Cascade>

デフォルト	false
要否	省略可
種類	ブール値
有効な値	`true` または `false`

<EndUserId> 要素

取り消すトークンのアプリエンドユーザー ID を指定します。ユーザー ID を格納する変数またはリテラルのトークン文字列を渡します。

<EndUserId>userIdString</EndUserId>

or:

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

デフォルト	`request.formparam.enduser_id`（x-www-form-urlencoded、リクエスト本文で指定）
プレゼンス	省略可
タイプ	文字列
有効な値	ユーザー ID 文字列を含むフロー変数またはリテラル文字列のどちらか

<RevokeBeforeTimestamp> 要素

タイムスタンプの値以前に発行されたトークンを取り消します。この要素は <AppId> および <EndUserId> と連携するため、特定の時間より前のトークンを取り消すことができます。デフォルト値はポリシーが実行される時刻です。

<RevokeBeforeTimestamp>timeStampString</RevokeBeforeTimestamp>

or:

<RevokeBeforeTimestamp ref="request.queryparam.revoke_since_timestamp"></RevokeBeforeTimestamp>

デフォルト	ポリシーが実行されるタイムスタンプ。
プレゼンス	省略可
種類	1970 年 1 月 1 日の午前 0 時（UTC）からの経過時間（ミリ秒）を表す 64 ビット（long 型）の整数。
有効な値	タイムスタンプを含むフロー変数、またはリテラルのタイムスタンプ。タイムスタンプの値は未来、または 2014 年 1 月 1 日より前にすることはできません。

フロー変数

RevokeOAuthV2 ポリシーではフロー変数は設定されません。

エラーリファレンス

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.InvalidFutureTimestamp`	500	Timestamp cannot be in the future.
`steps.oauth.v2.InvalidEarlyTimestamp`	500	Timestamp cannot be earlier than January 1, 2014.
`steps.oauth.v2.InvalidTimestamp`	500	Timestamp is invalid.
`steps.oauth.v2.EmptyAppAndEndUserId`	500	Both `AppdId` and `EndUserId` cannot be empty.

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":"Timestamp is in the future.",
      "detail":{
         "errorcode":"steps.oauth.v2.InvalidFutureTimestamp"
      }
   }
}

Example fault rule

<FaultRule name="RevokeOAuthV2 Faults">
    <Step>
        <Name>AM-InvalidTimestamp</Name>
    </Step>
    <Condition>(fault.name = "InvalidFutureTimestamp")</Condition>
</FaultRule>