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

下表介绍了所有政策父元素通用的特性：

属性 说明 默认 Presence
name

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

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

 不适用 必需
continueOnError

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

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

 false 可选
enabled

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

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

 true 可选

<DisplayName> 元素

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

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

不适用

如果省略此元素，则会使用政策的 name 属性的值。
Presence 可选
类型 字符串

<AppId> 元素

指定要撤销的令牌的开发者应用 ID。传递一个包含应用 ID 或字面量应用 ID 的变量。

<AppId>appIdString</AppId>

or:

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

request.formparam.app_id（一个 x-www-form-urlencoded，并在请求正文中指定）
Presence

可选
类型 字符串
有效值

包含应用 ID 字符串或字面量字符串的流变量。

<Cascade> 元素

如果为 true 并且具有传统的不透明访问令牌，则在 <AppId> 或 <EndUserId> 匹配时，刷新令牌和访问令牌都将被撤消。如果您拥有 JWT 访问令牌，则系统只会撤消随访问令牌颁发的刷新令牌。根据设计，JWT 访问令牌无法撤消。 如果为 false，则仅撤消访问令牌并且刷新令牌保持不变。相同的行为仅适用于不透明的访问令牌。JWT 访问令牌无法撤消。

<Cascade>false<Cascade>
默认

false
Presence

可选
类型 布尔值
有效值 true 或 false

<EndUserId> 元素

指定要撤销的令牌的应用最终用户 ID。传递包含用户 ID 或字面量令牌字符串的变量。

<EndUserId>userIdString</EndUserId>

or:

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

request.formparam.enduser_id（一个 x-www-form-urlencoded，并在请求正文中指定）
Presence

可选
类型 字符串
有效值

包含用户 ID 字符串或字面量字符串的流变量。

<RevokeBeforeTimestamp> 元素

撤销在时间戳之前签发的令牌。此元素与 <AppId> 和 <EndUserId> 一起使用，可让您在特定时间撤销令牌。默认值为政策执行的时间。

<RevokeBeforeTimestamp>timeStampString</RevokeBeforeTimestamp>

or:

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

政策执行的时间戳。
Presence

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

包含时间戳或字面量时间戳的流变量。时间戳不能是将来的日期，且不得早于 2014 年 1 月 1 日。

流变量

RevokeOAuthV2 政策未设置流变量。

错误参考信息

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。 下面显示的错误名称是在发生错误时分配给 fault.name 变量的字符串。如需了解详情，请参阅下面的故障变量部分。

故障代码 HTTP 状态 原因
steps.oauth.v2.InvalidFutureTimestamp 500 时间戳不能是将来的时间。
steps.oauth.v2.InvalidEarlyTimestamp 500 时间戳不得早于 2014 年 1 月 1 日。
steps.oauth.v2.InvalidTimestamp 500 时间戳无效。
steps.oauth.v2.EmptyAppAndEndUserId 500 AppdId 和 EndUserId 均不能为空。

部署错误

如需了解部署错误，请参阅界面中报告的消息。

故障变量

当此政策在运行时触发错误时，将设置这些变量。

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

故障规则示例

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

相关主题