OAuthV2 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

政策图标

内容

OAuthV2 是一种多方政策，用于执行 OAuth 2.0 授权类型操作。这是在 Apigee 上配置 OAuth 2.0 端点的主要政策。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

如需详细了解 Apigee 上的 OAuth，请参阅 OAuth 首页。它提供了资源、示例、视频等内容的链接。

示例

VerifyAccessToken

VerifyAccessToken

此 OAuthV2 政策配置（通过 VerifyAccessToken 操作）会验证提交到 Apigee 的访问令牌是否有效。当此政策操作被触发时，Apigee 会在请求中查找有效的访问令牌。如果访问令牌有效，则允许该请求继续。如果无效，所有处理都将停止，并在响应中返回错误。

<OAuthV2 name="OAuthV2-Verify-Access-Token">
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

客户端应用需要在包含令牌的请求中发送。例如，使用 curl，可能会如下所示：

$ curl https://API_ENDPOINT/weather/forecastrss?w=12797282 \
  -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"

其中，API_ENDPOINT 是用于访问 API 的网域，如 Apigee 系统中所配置。

默认情况下，OAuthV2 政策会从 Authorization 标头中提取访问令牌，以去除 Bearer 前缀。您可以使用 AccessToken 配置元素更改此默认行为。

GenerateAccessToken

生成访问令牌

如需查看针对每种支持的授权类型请求访问令牌的示例，请参阅获取 OAuth 2.0 令牌。本主题包括以下操作的示例：

GenerateAuthorizationCode

生成授权代码

如需查看有关如何请求授权代码，请参阅请求授权代码。

RefreshAccessToken

刷新访问令牌

如需了解如何使用刷新令牌请求访问令牌，请参阅刷新访问令牌。

JWT 访问令牌

JWT 访问令牌

有关如何生成、验证和刷新 JWT 访问令牌的示例，请参阅使用 JWT 访问令牌。

响应流令牌

生成响应流访问令牌

有时，您可能需要在响应流中生成访问令牌。例如，您可以这样做，以回应后端服务中的一些自定义验证。在此示例中，用例需要访问令牌和刷新令牌，而非隐式授权类型。在这种情况下，我们将使用密码授权类型来生成令牌。如您所见，实现此操作的技巧是传入带有 JavaScript 政策的授权请求标头。

首先，让我们来看看示例政策：

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

如果您将此政策放入响应流，那么即使在政策中指定正确的登录参数，它也会失败并显示“401 未经授权”错误。要解决此问题，您需要设置授权请求标头。

授权标头必须包含具有 Base64 编码的 client_id:client_secret 的基本访问方案。

您可以添加此标头，并将 JavaScript 政策置于 OAuthV2 政策前，就像这样。“local_clientid”和“local_secret”上下文变量必须预先设置并可以在流中使用：

var clientId = context.getVariable("local_clientid");
var clientSecret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+ CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(clientId + ':' + clientSecret)));

另请参阅对基本身份验证凭据进行编码。

元素参考

政策参考介绍了 OAuthV2 政策的元素和属性。

下面所示的示例政策是多种可能的配置之一。此示例展示了为 GenerateAccessToken 操作配置的 OAuthV2 政策。它包含必需和可选元素。如需了解详情，请参阅本部分中的元素说明。

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

<OAuthV2> 属性

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

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

属性 说明 默认 Presence
name

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

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

 不适用 必需
continueOnError

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

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

 false 可选
enabled

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

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

 true 可选
async

此特性已弃用。

 false 已弃用

<DisplayName> 元素

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

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

不适用

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

<AccessToken> 元素

<AccessToken>request.header.access_token</AccessToken>

默认情况下，当 Operation 为 VerifyAccessToken 时，政策会要求访问令牌以不记名令牌的形式在 Authorization 标头中发送；也就是说，前缀为“Bearer”，后跟一个空格。您可以使用此元素更改默认值，指定包含要验证的访问令牌的变量名称。使用此元素时，默认情况下，政策不会在变量的内容中查找前缀。如果要指定政策应查找前缀，请也使用 AccessTokenPrefix 元素。

示例：

  • 如果政策配置如下：

      <OAuthV2 name="OAuthV2-Verify-Access-Token-in-Header">
      <Operation>VerifyAccessToken</Operation>
      <AccessToken>request.header.access_token</AccessToken>
  </OAuthV2>

    如需使用 curl 传递令牌，您可以使用以下命令：

      curl https://API_ENDPOINT/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

  • 如果政策配置如下：

      <OAuthV2 name="OAuthV2-Verify-Access-Token-in-QueryParam">
      <Operation>VerifyAccessToken</Operation>
      <AccessToken>request.queryparam.token</AccessToken>
  </OAuthV2>

    如需使用 curl 传递令牌，您可以使用以下命令：

      curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"

其中，API_ENDPOINT 是用于访问 API 的网域，如 Apigee 系统中所配置。

默认：

不适用

状态：

可选
类型： 字符串
有效值：

任何变量名称
与操作配合使用：
  • VerifyAccessToken

<AccessTokenPrefix> 元素

<AccessTokenPrefix>Prefix</AccessTokenPrefix>

默认情况下，当 Operation 为 VerifyAccessToken 时，政策会要求访问令牌以不记名令牌的形式在 Authorization 标头中发送；也就是说，前缀为“Bearer”，后跟一个空格。如果您使用 AccessToken 元素为传入的访问令牌指定其他位置，则还可以使用此元素 AccessTokenPrefix 来指定其他非标准前缀。

例如，如果您指定以下条件：

<OAuthV2 name="OAuthV2-Verify-Access-Token-Alternative-Header">
    <Operation>VerifyAccessToken</Operation>
    <AccessToken>request.header.token</AccessToken>
    <AccessTokenPrefix>KEY</AccessTokenPrefix>
</OAuthV2>

然后，政策将从 token 请求标头中提取入站访问令牌，方式为：如果标头以“KEY”开头，后跟空格，则政策将删除该前缀和空格，并将剩余值解释为访问令牌。如果标头中不存在指定的前缀，则政策将抛出一个错误。

如果您指定 AccessToken 元素，但未指定 AccessTokenPrefix 元素，则政策会将 AccessToken 元素中指定的变量的整个值解释为访问令牌。

只要在还使用了 AccessToken 元素时，此元素才有效。

默认：

-无-

状态：

可选
类型： 字符串
有效值：

任何字符串
与操作配合使用：
  • VerifyAccessToken

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

指定用于为 JWT 访问令牌签名的加密算法。RSA (RS*) 算法使用公钥/密钥对，而 HMAC (HS*) 算法使用共享密钥。此元素对于 GenerateJWTAccessToken、VerifyJWTAccessToken 和 RefreshJWTAccessToken 操作是必需的。

默认 不适用
Presence 使用 GenerateJWTAccessToken、VerifyJWTAccessToken 和 RefreshJWTAccessToken 操作时是必需的。
类型 字符串
有效值 HS256、HS384、HS512、RS256、RS384、RS512

<AppEndUser> 元素

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

如果必须将应用最终用户 ID 发送到授权服务器，则可以使用此元素指定 Apigee 在何处查找最终用户 ID。例如，它可以作为查询参数或 HTTP 标头发送。

例如，request.queryparam.app_enduser 表示 AppEndUser 应以查询参数的形式显示，例如 ?app_enduser=ntesla@theramin.com。例如，如需在 HTTP 标头中提供 AppEndUser，请将此值设置为 request.header.app_enduser。

通过提供此设置，您可以在访问令牌中加入应用最终用户 ID。如果您希望能够按最终用户 ID 检索或撤消 OAuth 2.0 访问令牌，此功能会非常有用。有关详情，请参阅通过最终用户 ID 和/或应用 ID 检索和撤消 OAuth 2.0 访问令牌。

默认：

不适用

状态：

可选
类型： 字符串
有效值：

运行时可访问政策的任何流变量。
与授权类型配合使用：
  • authorization_code
  • 隐式
  • 密码
  • client_credentials

<Attributes/Attribute>

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

使用此元素将自定义属性添加到访问令牌或授权代码中。例如，您可能希望在可在运行时提取和检查的访问令牌中嵌入用户 ID 或会话标识符。

此元素让您可以在流变量或文字字符串中指定值。如果您同时指定变量和字符串，则使用流程变量中指定的值。如果无法解析该变量，则字符串为默认。

如需详细了解如何使用此元素，请参阅自定义令牌和授权代码。

在响应中显示或隐藏自定义属性

请记住，如果您将此政策的 GenerateResponse 元素设置为 true，则响应中会返回完整的 JSON 表示法，包括您设置的所有自定义属性。在某些情况下，您可能希望在响应中隐藏部分或所有自定义属性，以免客户端应用看到这些属性。

默认情况下，响应中会显示自定义属性。如果要将其隐藏，您可以将显示参数设置为 false。例如：

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

但 display 属性的值不会保留。假设您生成一个访问令牌，且您要在生成的响应中隐藏自定义属性。设置 display=false 可实现此目的。不过，如果稍后使用刷新令牌生成新访问令牌，则访问令牌中的原始自定义属性将显示在刷新令牌响应中。这是因为 Apigee 不会记住在生成访问令牌政策中最初将 display 属性设置为 false，该属性只是访问令牌元数据的一部分。

如果您向授权代码添加自定义属性，也会发现相同的行为。使用该代码生成访问令牌时，这些自定义属性将显示在访问令牌响应中。再次强调，这可能不是您期望的行为。

在这种情况下，要隐藏自定义属性，您可以选择：

  • 在刷新令牌政策中明确重置自定义属性，并将其显示设置为 false。在这种情况下，您可能需要使用 GetOAuthV2Info 政策从原始访问令牌中检索原始自定义值。
  • 使用后处理 JavaScript 政策手动提取您不想在响应中看到的任何自定义属性。

另请参阅自定义令牌和授权代码。

默认：

N/A

状态：

可选
有效值：
  • name -属性名称
  • ref - 属性名称。可能来自流变量。
  • display - （可选）可让您指定是否在响应中显示自定义属性。如果为 true，则响应中会出现自定义属性（如果还启用 GenerateResponse）。如果为 false，则响应中不会包含自定义属性。默认值为 true。请参阅在响应中显示或隐藏自定义属性。
与授权类型配合使用：
  • authorization_code
  • 隐式
  • 密码
  • client_credentials
  • refresh_token
  • 也可与 GenerateAuthorizationCode 操作配合使用。

<CacheExpiryInSeconds> 元素

<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>

此元素会对缓存强制执行 TTL，从而自定义缓存访问令牌到期的时间段。 支持的范围介于 1 到 180 秒之间。您可以提供流变量和默认变量。 如果提供，则流变量值优先于指定的默认值。

此元素只能用于 VerifyAccessToken 操作。

默认 不适用

如果您省略此元素，则缓存访问令牌的默认有效期为 180 秒。
Presence 可选
类型 整数
有效值 任何非零正整数。指定到期时间（以秒为单位）。

属性

下表说明 <CacheExpiryInSeconds> 元素的属性

属性 说明 默认 Presence
ref

对包含缓存到期时间值（以秒为单位）的流变量的引用。

如果提供，则流变量值优先于指定的默认值。

 不适用 可选

<ClientId> 元素

<ClientId>request.formparam.client_id</ClientId>

在很多情况下，客户端应用必须将客户端 ID 发送到授权服务器。通过此元素，您可以指定 Apigee 应在何处查找客户端 ID。您可以设置的唯一有效位置是默认位置，即流变量 request.formparam.client_id。不支持将 ClientId 设置为任何其他变量。另请参阅获取 OAuth 2.0 令牌。

默认：

request.formparam.client_id（x www-www-form-urlencoded 并在请求正文中指定）

状态：

可选
类型： 字符串
有效值： 流变量：request.formparam.client_id
与授权类型配合使用：
  • authorization_code
  • 密码
  • 隐式
  • client_credentials

也可与 GenerateAuthorizationCode 操作配合使用。

<Code> 元素

<Code>request.queryparam.code</Code>

在授权类型流程中，客户端必须将授权代码提交到授权服务器 (Apigee)。通过此元素，您可以指定 Apigee 应在何处查找授权代码。例如，它可以作为查询参数、HTTP 标头或表单参数（默认）发送。

变量 request.queryparam.auth_code 表示授权代码应显示为查询参数，例如 ?auth_code=AfGlvs9。例如，如需 HTTP 标头中的授权代码，可将此值设为 request.header.auth_code。另请参阅获取 OAuth 2.0 令牌。

默认：

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

状态：

可选
类型： 字符串
有效值： 运行时可访问政策的任何流变量
与授权类型配合使用： authorization_code

<ExpiresIn> 元素

<ExpiresIn>10000</ExpiresIn>

强制以毫秒为单位执行访问令牌和授权代码的过期时间。（对于刷新令牌，请使用 <RefreshTokenExpiresIn>。）过期时间值是系统生成的值加上 <ExpiresIn> 值。如果 <ExpiresIn> 设置为 -1，则令牌或代码会根据 OAuth 访问令牌有效期的最大值到期。如果未指定 <ExpiresIn>，则系统会应用在系统级别配置的默认值。

您也可以在运行时使用硬编码的默认值或参考流变量来设置过期时间。例如，您可以在键值对映射中存储令牌过期时间值，检索它，将其分配给变量，然后在政策中参考。例如，kvm.oauth.expires_in。

访问实体后，Apigee 会将以下实体缓存至少 180 秒。

  • OAuth 访问令牌。这意味着 OAuth v2 政策上的 ExpiresIn 元素无法在 180 秒之内使访问令牌到期。
  • 密钥管理服务 (KMS) 实体（应用、开发者、API 产品）。
  • OAuth 令牌和 KMS 实体的自定义属性。

以下节指定了一个流变量和一个默认值。请注意，流变量值优先于指定的默认值。

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

Apigee 不支持在创建令牌后强制使令牌过期。如果您需要强制令牌到期（例如，基于某个条件），此 Apigee 社区帖子中介绍了可能的解决方案。

默认情况下，过期的访问令牌会在过期的 3 天后自动从 Apigee 系统完全清除。另请参阅完全清除访问令牌

默认：

如果未指定，则系统会应用在系统级别配置的默认值。

状态：

可选
类型： 整数
有效值：
  • 任何非零正整数。指定以毫秒为单位表示的过期时间。虽然此元素的值以毫秒为单位，但令牌的 expires_in 属性和 expires_in 流变量中设置的值以秒为单位。
  • 根据 OAuth 访问令牌的过期期限，-1 将到期。

    注意：指定任何其他负整数或零会导致部署错误。
与授权类型配合使用：
  • authorization_code
  • 隐式
  • 密码
  • client_credentials
  • refresh_token

也可与 GenerateAuthorizationCode 操作配合使用。

<ExternalAccessToken> 元素

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

告知 Apigee 在何处查找外部访问令牌（非 Apigee 生成的访问令牌）。

变量 request.queryparam.external_access_token 表示外部访问令牌应作为查询参数显示，例如 ?external_access_token=12345678。例如，要在 HTTP 标头中请求外部访问令牌，请将此值设置为 request.header.external_access_token。另请参阅使用第三方 OAuth 令牌。

<ExternalAuthorization> 元素

<ExternalAuthorization>true</ExternalAuthorization>

如果此元素为 false 或不存在，则 Apigee 会根据 Apigee 授权存储区正常验证 client_id 和 client_secret。如果您要使用第三方 OAuth 令牌，请使用此元素。要详细了解如何使用此元素，请参阅使用第三方 OAuth 令牌。

默认：

false

状态：

可选
类型： 布尔值
有效值： true 或 false
与授权类型配合使用：
  • authorization_code
  • 密码
  • client_credentials

<ExternalAuthorizationCode> 元素

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

告知 Apigee 在何处查找外部授权代码（不是 Apigee 生成的授权代码）。

变量 request.queryparam.external_auth_code 表示外部授权代码应作为查询参数显示，例如 ?external_auth_code=12345678。例如，要在 HTTP 标头中要求外部授权代码，请将此值设置为 request.header.external_auth_code。另请参阅使用第三方 OAuth 令牌。

<ExternalRefreshToken> 元素

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

告知 Apigee 在何处可以找到外部刷新令牌（不是由 Apigee 生成的刷新令牌）。

变量 request.queryparam.external_refresh_token 表示外部刷新令牌应作为查询参数显示，例如 ?external_refresh_token=12345678。例如，要在 HTTP 标头中请求外部刷新令牌，请将此值设置为 request.header.external_refresh_token。另请参阅使用第三方 OAuth 令牌。

<GenerateResponse> 元素

<GenerateResponse enabled='true'/>

如果设置为 true 或省略 enabled 特性，则政策将生成并返回响应。例如，对于 GenerateAccessToken，响应可能如下所示：

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

如果设置为 false 或省略 <GenerateResponse> 元素，则不会发送任何响应。相反，一组流变量使用与政策的函数相关的值填充。例如，名为 oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code 的流变量将使用新创建的授权代码进行填充。请注意，expires_in 在响应中以秒为单位表示。

默认：

true

状态：

可选
类型： 字符串
有效值： true 或 false
与授权类型配合使用：
  • 隐式
  • 密码
  • client_credentials
  • refresh_token
  • 也可与 GenerateAuthorizationCode 操作配合使用。

<GenerateErrorResponse> 元素

<GenerateErrorResponse enabled='true'/>

如果设为 true，则如果 ContinueOnError 属性设置为 true，则政策将生成响应并返回响应。如果为 false（默认值），则不会发送响应。相反，一组流变量使用与政策的函数相关的值填充。

默认：

false

状态：

可选
类型： 字符串
有效值： true 或 false
与授权类型配合使用：
  • 隐式
  • 密码
  • client_credentials
  • refresh_token
  • 也可与 GenerateAuthorizationCode 操作配合使用。

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

告知政策在何处找到在请求中传递的授权类型参数。根据 OAuth 2.0 规范，必须向请求类型提供访问令牌和授权代码请求。变量可以是标头、查询参数或表单参数（默认）。

例如，request.queryparam.grant_type 表示密码应以查询参数的形式显示，例如 ?grant_type=password。例如，要在 HTTP 标头中请求授权类型，请将此值设置为 request.header.grant_type。另请参阅获取 OAuth 2.0 令牌。

默认：

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

状态：

可选
类型： 字符串
有效值： 如上所述的变量。
与授权类型配合使用：
  • authorization_code
  • 密码
  • 隐式
  • client_credentials
  • refresh_token

<Operation> 元素

<Operation>GenerateAuthorizationCode</Operation>

OAuth 2.0 操作由此政策执行。

默认：

如果未指定 <Operation>，Apigee 会查看 <SupportedGrantTypes> 列表。只有针对这些授权类型的操作才会成功。换句话说，如果您在 <SupportedGrantTypes> 列表中指定了 <GrantType>，则可以省略 <Operation>。如果 <Operation> 和 <SupportedGrantTypes> 均未指定，则默认授权类型是 authorization_code。也就是说，授权代码授权类型的请求将成功，但其他所有类型的请求将失败。

状态：

可选
类型： 字符串
有效值：
  • GenerateAccessToken - 生成访问令牌。另请参阅获取 OAuth 2.0 令牌。
  • GenerateAccessTokenImplicitGrant - 为隐式授权类型生成访问令牌。另请参阅获取 OAuth 2.0 令牌。
  • GenerateAuthorizationCode - 生成授权代码。与授权代码授权类型配合使用。另请参阅获取 OAuth 2.0 令牌。
  • RefreshAccessToken - 用刷新令牌换取新的访问令牌。另请参阅获取 OAuth 2.0 令牌。
  • VerifyAccessToken - 验证请求中发送的访问令牌是否有效。请参阅上面的 VerifyAccessToken 示例并验证访问令牌。
  • InvalidateToken - 撤消访问令牌。令牌撤消后，客户端将无法使用该令牌调用受保护的 API。另请参阅批准和撤消访问令牌。
  • ValidateToken - 恢复或“批准”之前撤消的访问令牌。另请参阅批准和撤消访问令牌。

其他 JWT 访问令牌操作

如果您更愿意使用 JWT 访问令牌而不是不透明的字符串令牌，则以下操作也可用于生成和验证 JWT 令牌。如需了解详情，请参阅使用 JWT OAuth 令牌操作：

  • GenerateJWTAccessToken - 生成具有已签名 JWT 的访问令牌。 请参阅生成 JWT 访问令牌。
  • GenerateJWTAccessTokenImplicitGrant - 为隐式授权类型生成具有已签名的 JWT 的访问令牌。请参阅生成 JWT 访问令牌。
  • VerifyJWTAccessToken - 验证已签名的 JWT 访问令牌。 另请参阅验证 JWT 访问令牌。
  • RefreshJWTAccessToken - 用刷新令牌换取新的 JWT 访问令牌。另请参阅刷新 JWT 访问令牌。

<PassWord> 元素

<PassWord>request.queryparam.password</PassWord>

此元素仅用于 密码授权类型。对于密码授权类型，必须向 OAuthV2 政策提供用户凭据（密码和用户名）。<PassWord> 和 <UserName> 元素用于指定 Apigee 找到这些值的变量。如果未指定这些元素，则政策将可在名为 username 和 password 的表单参数中查找值（默认）。如果未找到这些值，则政策会提示错误。您可以使用 <PassWord> 和 <UserName> 元素来参考包含凭据的任何流变量。

例如，您可以使用查询参数在令牌请求中传递密码，并设置如下所示的元素：<PassWord>request.queryparam.password</PassWord>.如需在 HTTP 标头中设置密码，请将此值设置为 request.header.password。

OAuthV2 政策不对这些凭据值执行任何其他操作；Apigee 只是验证它们是否显示。在令牌生成政策执行之前，由 API 开发者负责检索值请求并将其发送到身份提供商。

另请参阅获取 OAuth 2.0 令牌。

默认：

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

状态：

可选
类型： 字符串
有效值： 运行时任何政策可用的流变量。
与授权类型配合使用： 密码

<PrivateKey>/<Value>

<PrivateKey>
  <Value ref="variable-name-here"/>
</PrivateKey>

提供使用 RSA 算法验证或签署 JWT 格式访问令牌的私钥。 使用 ref 属性在流变量中传递密钥。仅在 Algorithm 元素值为 RS256、RS384 或 RS512 中的一个时使用。如需了解详情，请参阅使用 JWT OAuth 令牌操作。

默认 不适用
Presence 当 Algorithm 元素值为 HS256、HS384 或 HS512 中的一个时是必需的。
类型 字符串
有效值 包含 PEM 编码 RSA 私钥值的字符串的流变量。

<PublicKey>/<Value>

<PublicKey>
   <Value ref="variable-name-here"/>
</PublicKey>

指定用于验证使用 RSA 算法签署的 JWT 格式访问令牌上的签名的公钥或公共证书。使用 ref 属性在流变量中传递密钥/证书。仅在 Algorithm 元素值为 RS256、RS384 或 RS512 中的一个时使用。

默认 不适用
Presence 要验证使用 RSA 算法签署的 JWT，您必须使用证书、JWKS 或值元素。
类型 字符串
有效值 流变量或字符串。

<RedirectUri> 元素

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

指定 Apigee 应在请求中何处查找 redirect_uri 参数。

关于重定向 URI

重定向 URI 与授权代码和隐式授权类型配合使用。重定向 URI 告知授权服务器 (Apigee) 将授权代码发送到何处（适用于授权代码授权类型）或访问令牌（适用于隐式授权类型）。请务必了解何时需要此参数，何时可选以及此参数的使用方式：

  • （必需）如果使用与请求的客户端密钥关联的开发者应用注册回调网址，且请求中显示 redirect_uri，则这两个网址必须完全匹配。如果它们不匹配，则返回错误。如需了解如何在 Apigee 上注册开发者应用并指定回调网址，请参阅注册应用并管理 API 密钥。

  • （可选）如果已注册回调网址，并且请求中缺少 redirect_uri，则 Apigee 会重定向到已注册的回调网址。
  • （必需）如果未注册回调网址，则需要 redirect_uri。请注意，在这种情况下，Apigee 将接受任何网址。此案例可能会出现安全问题，因此应仅用于受信任的客户端应用。如果客户端应用不受信任，最佳做法是始终注册回调网址。

您可以在查询参数或标头中发送此参数。变量 request.queryparam.redirect_uri 表示 RedirectUri 应作为查询参数显示，例如 ?redirect_uri=login.myapp.com。例如，要在 HTTP 标头中提供 RedirectUri，请将此值设置为 request.header.redirect_uri。另请参阅获取 OAuth 2.0 令牌。

默认：

request.formparam.redirect_uri（x-www-form-urlencoded 并在请求正文中指定）

状态：

可选
类型： 字符串
有效值： 运行时可访问政策的任何流变量
与授权类型配合使用：
  • authorization_code
  • 隐式

与 GenerateAuthorizationCode 操作配合使用。

<RefreshToken> 元素

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

使用刷新令牌请求访问令牌时，必须在请求中提供刷新令牌。此元素可让您指定 Apigee 应在何处查找刷新令牌。例如，它可以作为查询参数、HTTP 标头或表单参数（默认）发送。

变量 request.queryparam.refreshtoken 表示刷新令牌应作为查询参数显示，例如 ?refresh_token=login.myapp.com。例如，要在 HTTP 标头中提供 RefreshToken，请将此值设置为 request.header.refresh_token。另请参阅获取 OAuth 2.0 令牌。

默认：

request.formparam.refresh_token（x www-www-form-urlencoded 并在请求正文中指定）

状态：

可选
类型： 字符串
有效值： 运行时可访问政策的任何流变量
与授权类型配合使用：
  • refresh_token

<RefreshTokenExpiresIn> 元素

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

强制以毫秒为单位执行刷新令牌的过期时间。过期时间值是系统生成的值加上 <RefreshTokenExpiresIn> 值。如果 <RefreshTokenExpiresIn> 设置为 -1，则刷新令牌会根据 OAuth 刷新令牌的有效期到期。如果未指定 <RefreshTokenExpiresIn>，则系统会应用默认值。

您也可以在运行时使用硬编码的默认值或参考流变量来设置过期时间。例如，您可以在键值对映射中存储令牌过期时间值，检索它，将其分配给变量，然后在政策中参考。例如：kvm.oauth.expires_in。

以下节指定了一个流变量和一个默认值。请注意，流变量值优先于指定的默认值。

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    86400000 <!--value in milliseconds-->
</RefreshTokenExpiresIn>

默认：

2592000000 毫秒（30 天）（自 2023 年 5 月 31 日起生效）

状态：

可选
类型： 整数
有效值：
  • 任何非零正整数。指定过期时间以毫秒为单位。
  • 根据 OAuth 刷新令牌的过期期限，-1 将到期。

    注意：指定任何其他负整数或零会导致部署错误。
与授权类型配合使用：
  • authorization_code
  • 密码
  • refresh_token

<ResponseType> 元素

<ResponseType>request.queryparam.response_type</ResponseType>

此元素用于告知 Apigee 客户端应用请求的授权类型。它仅与授权代码和隐式授权类型流程配合使用。

默认情况下，Apigee 会在 response_type 查询参数中查找响应类型值。如果要替换此默认行为，请使用 <ResponseType> 元素来配置包含响应类型值的流变量。例如，如果您将此元素设置为 request.header.response_type，则 Apigee 会查找在请求标头中传递的响应类型。另请参阅获取 OAuth 2.0 令牌。

默认：

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

状态：

可选。如果您希望替换默认行为，请使用此元素。
类型： 字符串
有效值： code（适用于授权代码授权类型）或 token（适用于隐式授权类型）
与授权类型配合使用：
  • 隐式
  • 与 GenerateAuthorizationCode 操作配合使用。

<ReuseRefreshToken> 元素

<ReuseRefreshToken>true</ReuseRefreshToken>

当设置为 true 时，现有的刷新令牌会被重复使用，直到其过期为止。如果为 false，则在提供有效的刷新令牌时，Apigee 会发出新的刷新令牌。

默认：

false

状态：

可选
类型： 布尔值
有效值：

true 或 false
与授权类型配合使用：
  • refresh_token

<RFCCompliantRequestResponse> 元素

<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>

如果为 true，则政策符合 RFC6749 标准，并且启用以下合规行为：

  • 错误和非错误响应将包含 HTTP Cache-Control 响应标头字段，以符合 RFC2616（超文本传输协议 -- HTTP/1.1），值为 no-store（在包含令牌、凭据或其他敏感信息的任何响应中）以及值为 no-cache 的 Pragma 响应标头字段。
  • expires_in 属性将以字母数字格式表示。为了保持一致性，refresh_token_expires_in 也是字母数字。
  • 用于生成令牌的 OAuthV2 响应将包含符合 RFC 标准的 Bearer 标头字段，而不是 BearerToken。
  • 响应载荷中的错误消息会采用以下格式：{"error" : "xxx", "error_description" :"yyy"} 用于刷新令牌错误。

默认：

false：默认情况下，该政策允许某些不符合 RFC 规范的行为。如需了解详情，请参阅不符合 RFC 的行为。将此元素设置为 true 以启用 RFC 合规性。

状态：

可选
类型： 布尔值
有效值： true 或 false
与授权类型配合使用： 全部

<SecretKey>/<Value>

<SecretKey>
  <Value ref="your-variable-name"/>
</SecretKey>

提供用于通过 HMAC 算法验证或签署的 JWT 格式访问令牌的密钥。仅在算法是 HS256、HS384、HS512 之一时使用。使用 ref 属性在流变量中传递密钥。如需了解详情，请参阅使用 JWT OAuth 令牌操作。

Apigee 为 HS256/HS384/HS512 算法强制执行最小密钥强度。HS256 的最小密钥长度为 32 个字节，HS384 为 48 个字节，而 HS512 则为 64 个字节。使用较低强度的密钥会导致运行时错误。

默认 不适用
Presence HMAC 算法所需的属性。
类型 字符串
有效值 流变量

<Scope> 元素

<Scope>request.queryparam.scope</Scope>

如果此元素存在于 GenerateAccessToken 或 GenerateAuthorizationCode 政策中，则用于指定授权令牌或代码的范围。这些值通常会传递给客户端应用中的政策。您可配置元素以采用流变量，同时可以选择范围在请求中的传递方式。在以下示例中，request.queryparam.scope 表示应显示为查询参数的范围，例如 ?scope=READ。例如，如需在 HTTP 标头中使用范围，请将此值设置为 request.header.scope。

如果该元素显示在“VerifyAccessToken”政策中，则用于指定此政策应该强制执行的范围。在此类政策中，该值必须为“硬编码”范围名称，但不能使用变量。例如：

<Scope>A B</Scope>

另请参阅使用 OAuth2 范围和获取 OAuth 2.0 令牌。

默认：

无范围

状态：

可选
类型： 字符串
有效值：

与生成*政策配合使用时，则为流变量。

与 VerifyAccessToken 配合使用时，空格分隔的范围名称列表（字符串）。
与授权类型配合使用：
  • authorization_code
  • 隐式
  • 密码
  • client_credentials
  • 也可用于 GenerateAuthorizationCode 和 VerifyAccessToken 操作。

<State> 元素

<State>request.queryparam.state</State>

如果客户端应用必须将状态信息发送给授权服务器，则此元素允许您指定 Apigee 应在何处查找状态值。例如，它可以作为查询参数或 HTTP 标头发送。状态值通常作为一种安全措施，用于防止 CSRF 攻击。

例如，request.queryparam.state 表示状态应该显示为查询参数，例如 ?state=HjoiuKJH32。例如，如需在 HTTP 标头中提供状态，请将此值设置为 request.header.state。另请参阅获取 OAuth 2.0 令牌。

默认：

无状态

状态：

可选
类型： 字符串
有效值： 运行时可访问政策的任何流变量
与授权类型配合使用：
  • 全部
  • 也可与 GenerateAuthorizationCode 操作配合使用

<StoreToken> 元素

 <StoreToken>true</StoreToken>

当 <ExternalAuthorization> 元素为 true 时，请将此元素设置为 true。<StoreToken> 元素告知 Apigee 存储外部访问令牌。否则将不会保留。

默认：

false

状态：

可选
类型： 布尔值
有效值： true 或 false
与授权类型配合使用：
  • authorization_code
  • 密码
  • client_credentials

<SupportedGrantTypes>/<GrantType> 元素

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

指定 Apigee 上 OAuth 令牌端点支持的授权类型。一个端点可支持多个授权类型（也就是说，可以配置端点为多个授权类型分配访问令牌）。如需详细了解端点，请参阅了解 OAuth 端点。授权类型在令牌请求中以 grant_type 参数的形式传递。

如果未指定受支持的授权类型，则仅允许的授权类型是 authorization_code 和 implicit。另请参阅 <GrantType> 元素（这是一个高级别元素，用于指定 Apigee 应在何处查找在客户端请求中传递的 grant_type 参数）。Apigee 将确保 grant_type 参数的值与某个受支持的授权类型匹配。

默认：

authorization _code 和隐式

状态：

必需
类型： 字符串
有效值：
  • client_credentials
  • authorization_code
  • 密码
  • 隐式

<Tokens>/<Token> 元素

与 ValidateToken 和 InvalidateToken 操作配合使用。另请参阅批准和撤消访问令牌。<Token> 元素可识别定义要撤销的令牌来源的流变量。例如，如果开发者想要将访问令牌作为名为 access_token 的查询参数提交，请使用 request.queryparam.access_token。

<UserName> 元素

<UserName>request.queryparam.user_name</UserName>

此元素仅用于 密码授权类型。对于密码授权类型，必须向 OAuthV2 政策提供用户凭据（密码和用户名）。<PassWord> 和 <UserName> 元素用于指定 Apigee 找到这些值的变量。如果未指定这些元素，则政策将可在名为 username 和 password 的表单参数中查找值（默认）。如果未找到这些值，则政策会提示错误。您可以使用 <PassWord> 和 <UserName> 元素来参考包含凭据的任何流变量。

例如，您可以在查询参数中传递用户名，并如下设置 <UserName> 元素：<UserName>request.queryparam.username</UserName>.如果要求在 HTTP 标头中提供用户名，请设置此值设为 request.header.username。

OAuthV2 政策不对这些凭据值执行任何其他操作；Apigee 只是验证它们是否显示。在令牌生成政策执行之前，由 API 开发者负责检索值请求并将其发送到身份提供商。

另请参阅获取 OAuth 2.0 令牌。

默认：

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

状态：

可选
类型： 字符串
有效值： 任何变量设置。
与授权类型配合使用： 密码

验证访问令牌

为 API 代理设置令牌端点后，将指定 VerifyAccessToken 操作的相应 OAuthV2 政策附加到公开受保护资源的流。

例如，为了确保向 API 发出的所有请求均获得授权，以下政策会强制执行访问令牌验证：

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

政策附加到受保护的 API 资源。为确保对 API 的所有请求都通过验证，请将政策附加到 ProxyEndpoint 请求 PreFlow，如下所示：

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

以下可选元素可用于替换 VerifyAccessToken 操作的默认设置。

名称 说明
范围

以空格分隔的范围列表。如果访问令牌中至少有一个列出的范围，则验证会成功。例如，以下政策将检查访问令牌，确保其中至少包含一个列出的范围。如果出现读或写，则验证成功。

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>
AccessToken 访问令牌防止位置的变量。例如：request.queryparam.accesstoken。默认情况下，根据 OAuth 2.0 规范，访问令牌应通过授权 HTTP 标头中的应用显示。如果访问令牌需在非标准位置（例如查询参数）或 HTTP 标头（名称并非授权）中显示，请使用此设置。

另请参阅验证访问令牌和获取 OAuth 2.0 令牌。

指定请求变量位置

对于每个授权类型，政策会对请求消息中的位置或必需信息做出假设。这些假设基于 OAuth 2.0 规范。如果您的应用需要违反 OAuth 2.0 规范，则可以为每个参数指定预期位置。例如，在处理授权代码时，您可以指定授权代码的位置、客户端 ID、重定向 URI 和范围。可以将它们指定为 HTTP 标头、查询参数或表单参数。

以下示例展示了如何将所需授权代码参数的位置指定为 HTTP 标头：

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

或者，如果您需要支持客户端应用基础，则可以混合使用标头和查询参数：

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

每个参数只能配置一个位置。

流变量

此表中定义的流变量在执行相应的 OAuth 政策时填充，因此可供在 API 代理流中执行的其他政策或应用使用。

VerifyAccessToken 操作

在 VerifyAccessToken 操作执行时，系统会在代理的执行上下文中填充大量流变量。这些变量会为您提供与访问令牌、开发者应用和开发者相关的属性。例如，您可以使用 AssignMessage 或 JavaScript 政策读取任何这些变量，并在流中稍后根据需要使用。这些变量还可用于调试。

令牌专用变量

变量 说明
organization_name 执行代理的组织名称。
developer.id 与已注册客户端应用关联的开发者或 AppGroup 的 ID。
developer.app.name 与已注册客户端应用关联的开发者或 AppGroup 应用的名称。
client_id 已注册客户端应用的客户端 ID。
grant_type 与请求关联的授权类型。 不支持 VerifyJWTAccessToken 操作。
token_type 与请求关联的令牌类型。
access_token 正在验证的访问令牌。
accesstoken.{custom_attribute} 访问令牌中已命名的自定义属性。
issued_at 访问令牌发放日期以 Unix 计时原点表达，以毫秒为单位。
expires_in 访问令牌的过期时间。以秒为单位表达。虽然 ExpiresIn 元素以毫秒为单位设置过期时间，但在令牌响应和流变量中，该值以秒为单位表达。
status 访问令牌的状态（例如已批准或已撤消）。
scope 与访问令牌关联的范围（如果有）。
apiproduct.<custom_attribute_name> 与已注册客户端应用关联的 API 产品的已命名自定义属性。
apiproduct.name 与已注册客户端应用关联的 API 产品的名称。
revoke_reason

（仅限 Apigee Hybrid）表示访问令牌被撤消的原因。 不支持 VerifyJWTAccessToken 操作。

值可以是 REVOKED_BY_APP、REVOKED_BY_ENDUSER、REVOKED_BY_APP_ENDUSER 或 TOKEN_REVOKED。

应用专用变量

这些变量与与令牌关联的开发者应用相关。

变量 说明
app.name
app.id
app.accessType
app.callbackUrl
app.status 已批准或已撤消
app.scopes
app.appFamily
app.apiproducts
app.appParentStatus
app.appType 例如：开发者
app.appParentId
app.created_by
app.created_at
app.last_modified_at
app.last_modified_by
app.{custom_attributes} 已注册客户端应用的已命名自定义属性。

AppGroup 专用变量

以下流变量包含有关令牌的 AppGroup 的信息，并由政策填充。仅当 verifyapikey.{policy_name}.app.appType 为“AppGroup”时，才会填充这些 AppGroup 属性。

变量 说明
appgroup.displayName AppGroup 显示名称。
appgroup.name AppGroup 的名称。
appgroup.id AppGroup ID。
appOwnerStatus 应用所有者的状态：“active”“inactive”或“login_lock”。
created_at AppGroup 的创建日期/时间戳。
created_by 创建 AppGroup 的开发者的电子邮件地址。
last_modified_at 上次修改 AppGroup 的日期/时间戳。
last_modified_by 上次修改 AppGroup 的开发者的电子邮件地址。
{appgroup_custom_attributes} 任何自定义 AppGroup 属性。指定自定义属性的名称。

开发者专用变量

如果 app.appType 为“开发者”，则填充开发者属性。

变量 说明
开发者专用变量
developer.id
developer.userName
developer.firstName
developer.lastName
developer.email
developer.status 活跃或非活跃
developer.apps
developer.created_by
developer.created_at
developer.last_modified_at
developer.last_modified_by
developer.{custom_attributes} 开发者的已命名自定义属性。

GenerateAuthorizationCode 操作

当 GenerateAuthorizationCode 操作成功执行时，将设置这些变量：

前缀： oauthv2authcode.{policy_name}.{variable_name}

示例： oauthv2authcode.GenerateCodePolicy.code

变量 说明
code 政策执行时生成的授权代码。
redirect_uri 与已注册客户端应用关联的重定向 URI。
scope 在客户端请求中传递的可选 OAuth 范围。
client_id 客户端请求中传递的客户端 ID。

GenerateAccessToken 和 RefreshAccessToken 操作

当 GenerateAccessToken 和 RefreshAccessToken 操作成功执行时，将设置这些变量。请注意，刷新令牌变量不适用于客户端凭据授权类型流。

前缀： oauthv2accesstoken.{policy_name}.{variable_name}

示例： oauthv2accesstoken.GenerateTokenPolicy.access_token

变量名称 说明
access_token 生成的访问令牌。
client_id 与此令牌关联的开发者应用的客户端 ID。
expires_in 令牌的到期值。如需了解详情，请参阅 <ExpiresIn> 元素。请注意，在响应中，expires_in 以秒为单位表示。
scope 为令牌配置的可用范围列表。请参阅使用 OAuth2 范围。
status approved 或 revoked。
token_type 设置为 BearerToken。
developer.email 拥有与令牌关联的开发者应用的已注册开发者的电子邮件地址。
organization_name 执行代理的组织。
api_product_list 与令牌的相应开发者应用关联的产品列表。
refresh_count
refresh_token 生成的刷新令牌。请注意，系统不会为客户端凭据授权类型生成刷新令牌。
refresh_token_expires_in 刷新令牌的有效期（以秒为单位）。
refresh_token_issued_at 此时间值是相应的 32 位时间戳数量的字符串表示形式。例如，“2013 年 8 月 21 日星期三 19:16:47 世界协调时间 (UTC)”对应的时间戳值为 1377112607413。
refresh_token_status approved 或 revoked。

GenerateAccessTokenImplicitGrant

当为隐式授权类型流成功执行 GenerateAccessTokenImplicit 操作时，将设置这些变量。

前缀： oauthv2accesstoken.{policy_name}.{variable_name}

示例： oauthv2accesstoken.RefreshTokenPolicy.access_token

变量 说明
oauthv2accesstoken.access_token 执行政策时生成的访问令牌。
oauthv2accesstoken.{policy_name}.expires_in 令牌的到期值（以秒为单位）。有关详情，请参阅 <ExpiresIn> 元素。

错误参考信息

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

运行时错误

政策执行时可能会发生这些错误。

故障代码 HTTP 状态 原因 由操作抛出
steps.oauth.v2.access_token_expired 401 访问令牌已过期。

VerifyAccessToken
InvalidateToken
steps.oauth.v2.access_token_not_approved 401 访问令牌已被撤消。 VerifyAccessToken
steps.oauth.v2.apiresource_doesnot_exist 401 所请求的资源不存在与访问令牌关联的任何 API 产品。 VerifyAccessToken
steps.oauth.v2.FailedToResolveAccessToken 500 政策应在 <AccessToken> 元素中指定的变量中找到访问令牌，但无法解析该变量。 GenerateAccessToken
steps.oauth.v2.FailedToResolveAuthorizationCode 500 政策应在 <Code> 元素中指定的变量中找到授权代码，但无法解析该变量。 GenerateAuthorizationCode
steps.oauth.v2.FailedToResolveClientId 500 政策应在 <ClientId> 元素中指定的变量中找到客户端 ID，但无法解析该变量。 GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.FailedToResolveRefreshToken 500 政策应在 <RefreshToken> 元素中指定的变量中找到刷新令牌，但无法解析该变量。 RefreshAccessToken
steps.oauth.v2.FailedToResolveToken 500 政策应在 <Tokens> 元素中指定的变量中找到令牌，但无法解析该变量。

ValidateToken
InvalidateToken
steps.oauth.v2.InsufficientScope 403 请求中提供的访问令牌的范围与验证访问令牌政策中指定的范围不匹配。要了解范围，请参阅使用 OAuth2 范围。 VerifyAccessToken
steps.oauth.v2.invalid_access_token 401 从客户端发送的访问令牌无效。 VerifyAccessToken
steps.oauth.v2.invalid_client 401

将政策的 <GenerateResponse> 属性设置为 true，且在请求中发送的客户端 ID 无效时，系统会返回此错误名称。检查确保您在使用与代理关联的开发者应用的正确客户端密钥和密钥值。这些值通常作为 Base64 编码的基本授权标头发送。

 GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.invalid_request 400 此错误名称用于多种不同类型的错误，通常适用于在请求中发送的丢失或不正确参数。如果将 <GenerateResponse> 设置为 false，则使用故障变量（如下所述）来检索错误的详细信息，例如故障名称和原因。 GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.InvalidAccessToken 401 授权标头没有必须的单词 Bearer。例如：Authorization: Bearer your_access_token VerifyAccessToken
steps.oauth.v2.InvalidAPICallAsNo\
ApiProductMatchFound		 401

当前正在执行的 API 代理或操作不在与访问令牌相关联的产品中。

提示：确保与访问令牌关联的产品已正确配置。例如，如果在资源路径中使用通配符，请确保正确使用通配符。如需了解详情，请参阅管理 API 产品。

有关此错误原因的更多说明，另请参阅 Oauth2.0 Access Token Verification 抛出的“由于未找到 apiproduct 匹配项，API 调用无效”的错误。

 VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier 500

将政策的 <GenerateResponse> 属性设置为 false，且在请求中发送的客户端 ID 无效时，系统会返回此错误名称。检查确保您在使用与代理关联的开发者应用的正确客户端密钥和密钥值。这些值通常作为 Base64 编码的基本授权标头发送。

GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.InvalidParameter 500 政策必须指定访问令牌或授权代码，但不能同时指定这两者。 GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.InvalidTokenType 500 <Tokens>/<Token> 元素要求您指定令牌类型（例如 refreshtoken）。如果客户端传递的类型不正确，则会抛出此错误。 ValidateToken
InvalidateToken
steps.oauth.v2.MissingParameter 500 响应类型为 token，但未指定授权类型。 GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.UnSupportedGrantType 500

客户端指定的授权类型不受政策支持（未在 <SupportedGrantTypes> 元素中列出）。

 GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken

特定于 JWT 令牌的运行时错误

JWT 身份验证令牌流的运行时错误代码和说明取决于 OAuth2 流上下文：

JWT 令牌生成和刷新流的错误代码

对于生成或刷新 JWT 令牌的 OAuth2 流程，错误响应遵循 RFC6749 中指定的错误响应。如需了解详情，请参阅第 5.2 节错误响应。

令牌验证流程的错误代码

下表列出的错误代码仅适用于 VerifyAccessToken 操作。

故障代码 HTTP 状态 原因 由操作抛出
oauth.v2.JWTSigningFailed 401 该政策无法签署 JWT。

GenerateJWTAccessToken
oauth.v2.InvalidValueForJWTAlgorithm 401 如果 JWT 访问令牌中不存在该算法，或者该值不受支持，就会发生这种情况。

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.InsufficientKeyLength 401 生成 JWT 时，HS384 或 HS512 算法的密钥大小小于下限。

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.JWTAlgorithmMismatch 401 生成政策中指定的算法与验证政策中要求的算法不匹配。指定的算法必须匹配。

VerifyJWTAccessToken
oauth.v2.JWTDecodingFailed 401 该政策无法解码 JWT。JWT 可能已损坏。

VerifyJWTAccessToken
oauth.v2.MissingMandatoryClaimsInJWT 401 当 JWT 访问令牌中不存在必需的声明时出现。

VerifyJWTAccessToken
oauth.v2.InvalidJWTSignature 401 如果无法验证 JWT 访问令牌的签名，或者签名无效，就会发生这种情况。

VerifyJWTAccessToken
oauth.v2.InvalidTypeInJWTHeader 401 在 JWT 的类型不是 at+Jwt 时出现。

VerifyJWTAccessToken

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

错误名称 原因
InvalidValueForExpiresIn

对于 <ExpiresIn> 元素，有效值为正整数和 -1。
InvalidValueForRefreshTokenExpiresIn 对于 <RefreshTokenExpiresIn> 元素，有效值为正整数和 -1。
InvalidGrantType 在 <SupportedGrantTypes> 元素中指定的授权类型无效。请参阅政策参考，获取有效类型的列表。
ExpiresInNotApplicableForOperation 确保在 <Operations> 元素中指定的操作支持到期。例如，VerifyToken 操作不支持。
RefreshTokenExpiresInNotApplicableForOperation 确保在 <Operations> 元素中指定的操作支持刷新令牌到期。例如，VerifyToken 操作不支持。
GrantTypesNotApplicableForOperation 请确保指定的操作支持在 <SupportedGrantTypes> 中指定的授权类型。
OperationRequired

您必须使用 <Operation> 元素在此政策中指定操作。
InvalidOperation

您必须使用 <Operation> 元素在此政策中指定有效的操作。
TokenValueRequired 您必须在 <Tokens> 元素中指定一个令牌 <Token> 值。

特定于 JWT 令牌的部署错误

这些部署错误特定于使用 JWT 令牌操作的政策。

错误名称 原因
InvalidValueForAlgorithm 在 <Algorithm> 元素中指定的算法不在可用算法列表中或者不存在。
MissingKeyConfiguration 缺少必需的 <SecretKey>、<PrivateKey> 或 <PublicKey> 元素，具体取决于所使用的算法。
EmptyValueElementForKeyConfiguration 未在 <PrivateKey>、<PublicKey> 或 <SecretKey> 元素中定义所需的子元素 <Value>
InvalidKeyConfiguration <PrivateKey> 元素未与 RSA 系列算法搭配使用，或者 <SecretKey> 元素未与 HS 系列算法搭配使用。
EmptyRefAttributeForKeyconfiguration <PrivateKey>、<PublicKey> 或 <SecretKey> 元素的子元素 <Value> 的 ref 属性为空。
InvalidVariableNameForKey 在 <PrivateKey>、<PublicKey> 或 <SecretKey> 元素的子元素 <Value> 的 ref 属性中指定的流变量名称不包含 private 前缀。

故障变量

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

变量 地点 示例
fault.name="fault_name" fault_name 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。 fault.name = "invalid_request"
oauthV2.policy_name.failed policy_name 是抛出故障的政策的用户指定名称。 oauthV2.GenerateAccesstoken.failed = true
oauthV2.policy_name.fault.name policy_name 是抛出故障的政策的用户指定名称。 oauthV2.GenerateAccesstoken.fault.name = invalid_request
oauthV2.policy_name.fault.cause policy_name 是抛出故障的政策的用户指定名称。 oauthV2.GenerateAccesstoken.cause = Required param : grant_type

错误响应示例

如果 <GenerateResponse> 元素为 true，则会将这些响应发送回客户端。

如果 <GenerateResponse> 为 true，则政策会针对生成令牌和代码的操作返回此格式的错误。如需完整列表，请参阅 OAuth HTTP 错误响应参考。

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

如果 <GenerateResponse> 为 true，则政策会针对验证和验证操作返回此格式的错误。如需完整列表，请参阅 OAuth HTTP 错误响应参考。

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

故障规则示例

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

对 Storage 中的令牌进行哈希处理

如果您使用的是 Apigee Hybrid 或 Apigee，则默认情况下，OAuthV2 访问令牌和刷新令牌会在存储在运行时 Cassandra 数据库中时进行哈希处理。哈希处理可防止数据库被入侵时使用令牌。

使用默认 OAuth 配置

Apigee 上的每个组织（甚至是免费适用组织）均使用 OAuth 令牌端点进行配置。端点在名为 OAuth 的 API 代理中预配置了政策。在 Apigee 上创建账号后，您可以立即开始使用令牌端点。如需了解详情，请参阅了解 OAuth 端点。

完全清除访问令牌

默认情况下，OAuth2 令牌将在访问令牌和刷新令牌（如果存在）过期 3 天（259200 秒）后，从 Apigee 系统中完全清除。

不符合 RFC 标准的行为

默认情况下，指定了 GenerateAccessToken 操作的 OAuthV2 政策会返回包含某些不符合 RFC 规范的属性的令牌响应。下表显示了 OAuthV2 政策返回的相应不合规属性以及相应的合规属性。

OAuthV2 返回： 符合 RFC 规范的属性为：
"token_type":"BearerToken" "token_type":"Bearer"
"expires_in":"3600" "expires_in":3600

（合规的值是一个数字，而不是字符串。）

此外，当 grant_type = refresh_token 如下时，过期的刷新令牌响应错误：

{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}

然而，符合 RFC 规范的响应为：

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

相关主题