OAuthV2 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

内容

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

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

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

示例

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

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

<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>

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

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

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

<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 系统中所配置。

<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 元素时，此元素才有效。

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

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

<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 访问令牌。

<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 政策手动提取您不想在响应中看到的任何自定义属性。

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

<CacheExpiryInSeconds> 元素

<CacheExpiryInSeconds ref="propertyset.settings.token-ttl">60</CacheExpiryInSeconds>

此元素只能用于 VerifyAccessToken 操作。它用于指定特定政策执行的访问令牌缓存的存活时间 (TTL)。Apigee 首次验证 OAuth 2 访问令牌时，必须从永久存储区检索访问令牌。这是一个相对耗时的操作，因此 Apigee 会缓存令牌查找的结果，包括令牌状态、令牌对其有效的产品列表，以及附加到令牌的任何自定义属性。在 TTL 过期之前，对 OAuthV2/VerifyAccessToken 的后续调用将读取内存中缓存的结果，这意味着令牌验证速度将会快得多。

访问令牌缓存的默认 TTL 为 180 秒。借助此元素，您可以缩短该 TTL，从而以性能换取正确性。在某些情况下，这样做很有用，例如，如果您有时会撤消令牌，并且希望缩短 Apigee 继续将已撤消的令牌视为有效的时间范围。

支持的范围介于 1 到 180 秒之间。您可以提供流变量和默认值。如果您提供的流变量包含数字值，则该值优先于指定的默认值。

属性

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

<ClientId> 元素

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

在很多情况下，客户端应用必须将客户端 ID 发送到授权服务器。该元素指定 Apigee 应在流变量 request.formparam.client_id 中查找客户端 ID。不支持将 ClientId 设置为任何其他变量。另请参阅获取 OAuth 2.0 令牌。

<Code> 元素

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

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

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

<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 系统完全清除。另请参阅完全清除访问令牌

<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 令牌。

<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 在响应中以秒为单位表示。

<GenerateErrorResponse> 元素

<GenerateErrorResponse enabled='true'/>

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

<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 令牌。

<Operation> 元素

<Operation>GenerateAuthorizationCode</Operation>

OAuth 2.0 操作由此政策执行。

<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 令牌。

<PrivateKey>/<Value>

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

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

<PublicKey>/<Value>

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

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

<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 令牌。

<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 令牌。

<RefreshTokenExpiresIn> 元素

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

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

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

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

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

<ResponseType> 元素

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

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

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

<ReuseRefreshToken> 元素

<ReuseRefreshToken>true</ReuseRefreshToken>

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

<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"} 用于刷新令牌错误。

<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 个字节。使用较低强度的密钥会导致运行时错误。

<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 令牌。

<State> 元素

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

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

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

<StoreToken> 元素

 <StoreToken>true</StoreToken>

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

<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 参数的值与某个受支持的授权类型匹配。

<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 令牌。

验证访问令牌

为 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>

另请参阅验证访问令牌和获取 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 政策读取任何这些变量，并在流中稍后根据需要使用。这些变量还可用于调试。

令牌专用变量

应用专用变量

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

AppGroup 专用变量

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

开发者专用变量

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

GenerateAuthorizationCode 操作

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

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

示例： oauthv2authcode.GenerateCodePolicy.code

GenerateAccessToken 和 RefreshAccessToken 操作

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

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

示例： oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

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

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

示例： oauthv2accesstoken.RefreshTokenPolicy.access_token

错误参考信息

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

运行时错误

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

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

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

• 如果流上下文是令牌生成或刷新，请参阅下面的 JWT 令牌生成和刷新流的错误代码。
• 如需了解令牌验证流程，请参阅下文中的令牌验证流程的错误代码。

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

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

令牌验证流程的错误代码

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

部署错误

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

特定于 JWT 令牌的部署错误

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

故障变量

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

错误响应示例

如果 <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 政策返回的相应不合规属性以及相应的合规属性。

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

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

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

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

相关主题

• OAuth 2.0 简介