撤消和批准令牌

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

了解令牌撤消

在某些情况下，应用需要明确撤消单个令牌或使其失效。典型的情况包括用户退出启用了 OAuth 的应用。撤消的令牌将无法再用于授权。令牌撤消后，如果应用向 API 代理提供该令牌，则带有 VerifyAccessToken 操作的 OAuthV2 政策将拒绝该令牌。

令牌撤消标准由 IETF RFC 7009（OAuth 2.0 令牌撤消规范）定义。

作为撤消特定令牌的替代方法，您可以撤消客户端 ID 或整个开发者应用。如需了解详情，请参阅撤消和批准开发者应用密钥。与撤消单个令牌相比，撤消客户端 ID 或开发者应用会产生更广泛的影响。撤消客户端 ID 或开发者应用时，Apigee 将拒绝与该客户端 ID 或开发者应用关联的所有令牌，并且将不再为该客户端 ID 或开发者应用颁发新令牌。

撤消令牌（访问令牌或刷新令牌）后，您可以选择在令牌到期前随时重新批准该令牌。重新批准令牌后，Apigee OAuthV2 政策将再次接受该令牌进行授权，直到令牌到期为止。令牌到期时间与令牌的已批准或已撤消状态无关。仅当访问令牌已获得批准（或未撤消）并且未到期时，操作为 ValidateAccessToken 的 Apigee OAuthV2 政策才会接受该令牌。同样，仅当访问令牌已获得批准（或未撤消）并且未到期时，操作为 RefreshAccessToken 的 Apigee OAuthV2 政策才会接受该令牌。

有两种政策可用于撤消令牌：

OAuthV2 政策一次可以撤消一个令牌，也可以恢复一个令牌。RevokeOAuthV2 政策更加灵活，可以按应用 ID 或最终用户 ID 一次撤消多个令牌。本页面的其余部分介绍了如何使用 OAuthV2 政策来撤消令牌或恢复先前撤消的令牌。

撤消访问令牌和刷新令牌

以下是使用 InvalidateToken 操作的 OAuthV2 政策的配置示例。在这种情况下，由于 Token 元素上的 cascade 属性为 true，因此 Apigee 会同时撤消访问令牌及其关联的刷新令牌。

  <OAuthV2 name="InvalidateToken">
    <Operation>InvalidateToken</Operation>
    <Tokens>
      <Token type="accesstoken" cascade="true">request.queryparam.token</Token>
    </Tokens>
  </OAuthV2>

如需详细了解级联标志的工作原理，请参阅以下有关令牌元素的特性的部分。

<Tokens>/<Token> 元素

标识指定要撤消的令牌的流变量。例如，开发者要使用名为 access_token 的查询参数提交撤消请求，则正确的流变量为：request.queryparam.access_token。例如，如需在 HTTP 标头中提供令牌，请将此值设置为 request.header.access_token。

无法撤消 JWT 格式的访问令牌。此外，您无法使用 OAuthV2 政策撤消与 JWT 格式的访问令牌关联的刷新令牌。如果此处指定的上下文变量引用 JWT 访问令牌，或与 JWT 访问令牌关联的刷新令牌，则会发生运行时错误。您可以使用 RevokeOAuthV2 政策撤消与 JWT 访问令牌关联的刷新令牌。

特性

  • type（必需，字符串）：由指定的变量标识的令牌类型。支持的值包括 accesstoken 和 refreshtoken:。
    • 要撤消访问令牌，请指定 accesstoken 类型。
    • 要同时撤消访问令牌和刷新令牌，请指定 refreshtoken 类型。当 Apigee 看到类型 refreshtoken 时，它会假定该令牌是刷新令牌。如果找到了该刷新令牌，则它会被撤消。如果未找到该刷新令牌，Apigee 会检查它是否为访问令牌。如果访问令牌存在，则它会被撤消。

      注意：如果您将已失效的令牌传递给 InvalidateToken 政策，您可能预期该政策会返回错误，但实际上并不会。此类操作无效。
  • cascade（可选，布尔值，默认值：true）此特性的主要用途是撤消刷新令牌，而不撤消其关联的访问令牌。考虑以下情况：
    • 仅撤消刷新令牌，不撤消其关联的访问令牌。为此，请将 <Token> 类型设置为 refreshtoken，并将 cascade 设置为 false。
    • 同时撤消访问令牌和刷新令牌。为此，请将 <Token> 类型设置为 accesstoken。cascade 的值可以是 true（默认值）或 false。如果将其设置为 true，则访问令牌和刷新令牌都会被撤消。如果将其设置为 false，则访问令牌会被撤消，并且刷新令牌不可用。请参阅以下备注了解详细说明。
    • 撤消访问令牌，并且不撤消其关联的刷新令牌。不支持。请参阅以下备注了解详细说明。

注意：出于安全原因，如果您撤消访问令牌，关联的刷新令牌也会被撤消。因此，您不能使用级联特性来仅撤消访问令牌。例如，如果您将 <Token> 类型设置为 accesstoken，并设置 cascade=false，则访问令牌会按预期被撤消；但关联的刷新令牌将不可用。它无法用于刷新已撤消的访问令牌。级联特性的主要用例是，您只想撤消刷新令牌。在这种情况下，请将 <Token> 类型设置为 refreshtoken，并设置 cascade=false。刷新令牌将被撤消，但其关联的访问令牌将保持有效（直到令牌过期或被撤消）。如需了解详情，请参阅此社区论坛讨论。

批准访问令牌和刷新令牌

使用 ValidateToken 操作来“重新批准”已撤消的令牌。也就是说，当您应用此操作时，目标访问或刷新令牌的状态会从“已撤消”更改为“已批准”。您可以验证任何未过期的已撤消令牌。

<OAuthV2 name="ValidateToken">
  <Operation>ValidateToken</Operation>
  <Tokens>
    <Token type="refreshtoken" cascade="true">flow.variable</Token>
  </Tokens>
</OAuthV2>

<Tokens>/<Token> 元素

标识指定要验证的令牌的流变量。例如，开发者要使用名为 access_token 的查询参数提交验证请求，则正确的流变量为：request.queryparam.access_token。例如，如需在 HTTP 标头中提供令牌，请将此值设置为 request.header.access_token。

特性

  • type（必需，字符串）由指定的变量标识的令牌类型。支持的值包括 accesstoken 和 refreshtoken。
  • cascade（可选，布尔值）：默认情况下，此选项设置为 true，这会使验证传播到关联的令牌。因此，如果应用于刷新令牌，其关联的访问令牌也会被验证。如果应用于访问令牌，其关联的刷新令牌也会被验证。如果将此选项设置为 false，则仅验证指定的访问令牌或刷新令牌。