撤销 OAuth V2 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 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。您可以通过将 <AppEndUser> 元素添加到 OAuthv2 政策，将 Apigee 配置为包含最终用户 ID：

<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 列表，请使用：

按应用的最终用户 ID 撤销

撤销与特定应用 ID 关联的 OAuth2 访问令牌。该令牌与将令牌发送到的用户的 ID 相关联。

默认情况下，OAuth 访问令牌中没有最终用户 ID 的字段。如需允许最终用户 ID 撤销 OAuth 2.0 访问令牌，您必须配置 OAuthv2 政策，以便在令牌中包含用户 ID。

要获取应用最终用户 ID，请使用 Method: organizations.developers.get。

示例

以下示例使用“撤消 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) epoch 时间。在此之前签发的所有令牌都将撤销。

以下示例撤销了在 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> 元素采用 64 位（长）整数，表示自世界协调时间 (UTC) 1970 年 1 月 1 日午夜以来的毫秒数。

元素参考

元素参考说明了 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 个字符。

（可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

 不适用 必需
continueOnError

设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。

设置为 true，即使在政策失败后，仍可以继续执行流。

 false 可选
enabled

设置为 true 可强制执行政策。

设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。

 true 可选

<DisplayName> 元素

用于在 name 属性之外在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>
默认

不适用

如果省略此元素，则会使用政策的 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>
默认值

政策执行的时间戳。
状态

可选
类型 64 位（长）整数，表示从世界协调时间 (UTC) 1970 年 1 月 1 日午夜开始计算的毫秒数。
有效值

包含时间戳或字面量时间戳的流变量。时间戳不能是将来的日期，且不得早于 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>

相关主题