OAuthV2 政策

您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

内容

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

提示：如果您想详细了解 Apigee Edge 上的 OAuth，请参阅 OAuth 首页。它提供了资源、示例、视频等内容的链接。如需了解如何在正常运行的应用中使用此政策，请参阅 GitHub 上的高级 OAuth 示例。

示例

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <Operation>VerifyAccessToken</Operation>
    <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer -->
</OAuthV2>

$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

<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 client_id = context.getVariable("local_clientid");
var client_secret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(client_id + ':' + client_secret)));

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

元素参考

政策参考介绍了 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>

默认情况下，VerifyAccessToken 会在 Authorization 标头中发送访问令牌。您可以使用此元素更改默认值。例如，request.queryparam.access_token 表示访问令牌应显示为名为 access_token 的查询参数。

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

<AccessTokenPrefix> 元素

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

默认情况下，VerifyAccessToken 需要访问令牌以不记名令牌的形式在授权标头中发送。例如：

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

目前，不记名是唯一受支持的前缀。

<AppEndUser> 元素

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

如果必须将应用最终用户 ID 发送到授权服务器，则可以使用此元素指定 Edge 在何处查找最终用户 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 可实现此目的。不过，如果稍后使用刷新令牌生成新访问令牌，则访问令牌中的原始自定义属性将显示在刷新令牌响应中。这是因为 Edge 不会记住在生成访问令牌政策中最初将 display 属性设置为 false，该属性只是访问令牌元数据的一部分。

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

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

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

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

<ClientId> 元素

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

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

<Code> 元素

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

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

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

<ExpiresIn> 元素

<ExpiresIn>10000</ExpiresIn> 

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

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

使用 Apigee Edge for Public Cloud 时，Edge 会在访问以下实体后将其缓存至少 180 秒。

• OAuth 访问令牌。这意味着，撤消的令牌可能仍会在长达三分钟内有效，直到其缓存限制过期为止。
• 密钥管理服务 (KMS) 实体（应用、开发者、API 产品）。
• OAuth 令牌和 KMS 实体的自定义属性。

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

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

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

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

私有云：对于适用于私有云的 Edge 安装，默认值由 conf_keymanagement_oauth_auth_code_expiry_time_in_millis 属性设置。如需设置此属性，请执行以下操作：

1. 通过编辑器打开 message-processor.properties 文件。 如果该文件不存在，请创建它：

   vi /opt/apigee/customer/application/message-processor.properties

2. 根据需要设置该属性：

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

3. 确保属性文件归“apigee”用户所有：

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. 重启消息处理器。

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

<ExternalAccessToken> 元素

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

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

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

<ExternalAuthorization> 元素

<ExternalAuthorization>true</ExternalAuthorization>

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

<ExternalAuthorizationCode> 元素

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

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

变量 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 Edge 在何处可以找到外部刷新令牌（不是由 Apigee Edge 生成的刷新令牌）。

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

<GenerateResponse> 元素

<GenerateResponse enabled='true'/>

如果设置为 true，则政策将生成并返回响应。例如，对于 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，则不会发送任何响应。相反，一组流变量使用与政策的函数相关的值填充。例如，名为 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。另请参阅请求访问令牌和授权代码。

<Operation> 元素

<Operation>GenerateAuthorizationCode</Operation>

OAuth 2.0 操作由此政策执行。

<PassWord> 元素

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

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

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

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

另请参阅请求访问令牌和授权代码。

<RedirectUri> 元素

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

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

关于重定向 URI

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

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

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

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

<RefreshToken> 元素

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

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

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

<RefreshTokenExpiresIn> 元素

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

强制以毫秒为单位执行刷新令牌的过期时间。过期时间值是系统生成的值加上 <RefreshTokenExpiresIn> 值。如果 <RefreshTokenExpiresIn> 设置为 -1，则刷新令牌会根据 OAuth 刷新令牌的有效期到期。如果未指定 <RefreshTokenExpiresIn>，则系统会应用在系统级别配置的默认值。如需详细了解默认系统设置，请与 Apigee Edge 支持团队联系。

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

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

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

私有云：对于适用于私有云的 Edge 安装，默认值由 conf_keymanagement_oauth_refresh_token_expiry_time_in_millis 属性设置。如需设置此属性，请执行以下操作：

1. 通过编辑器打开 message-processor.properties 文件。 如果该文件不存在，请创建它：

   vi /opt/apigee/customer/application/message-processor.properties

2. 根据需要设置该属性：

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

3. 确保属性文件归“apigee”用户所有：

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. 重启消息处理器。

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

<ResponseType> 元素

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

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

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

<ReuseRefreshToken> 元素

<ReuseRefreshToken>true</ReuseRefreshToken>

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

<Scope> 元素

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

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

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

<Scope>A B</Scope>

另请参阅使用 OAuth2 范围和请求访问令牌和授权代码。

<State> 元素

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

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

例如，request.queryparam.state 表示状态应该显示为查询参数，例如 ?state=HjoiuKJH32。例如，如需在 HTTP 标头中提供状态，请将此值设置为 request.header.state。另请参阅请求访问令牌和授权代码。

<StoreToken> 元素

 <StoreToken>true</StoreToken> 

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

<SupportedGrantTypes>/<GrantType> 元素

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

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

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

<Tokens>/<Token> 元素

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

<UserName> 元素

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

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

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

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

另请参阅请求访问令牌和授权代码。

验证访问令牌

为 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 规范，则可以为每个参数指定预期位置。例如，在处理授权代码时，您可以指定授权代码的位置、客户端 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 政策读取任何这些变量，并在流中稍后根据需要使用。这些变量还可用于调试。

令牌专用变量

应用专用变量

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

开发者专用变量

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

公司专用变量

如果 app.appType 为“公司”，则填充公司属性；如果 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

错误参考信息

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

运行时错误

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

部署错误

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

故障变量

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

错误响应示例

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

政策架构

每种政策类型均由 XML 架构 (.xsd) 定义。GitHub 提供了政策架构作为参考。

使用默认 OAuth 配置

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

完全清除访问令牌

默认情况下，OAuth2 令牌会在访问令牌和刷新令牌（如果存在）过期的 3 天（259200 秒）之后从 Apigee Edge 系统中完全清除。在某些情况下，您可能需要更改此默认值。例如，如果生成大量令牌，您可能希望缩短完全清除时间以节省磁盘空间。

如果您使用的是 Edge Private Cloud，则可以按照本部分所述设置组织属性来更改此默认值。（针对过期令牌的 3 天清除期限适用于 Edge for Private Cloud 4.19.01 及更高版本。对于早期版本，默认完全清除间隔为 180 天。）

更新 Edge Private Cloud 4.16.01 及更高版本的清除设置

注意：只有在应用这些设置之后生成的令牌会受到影响；这些设置不适用于之前生成的令牌。

更新了 Edge Private Cloud 4.15.07 的清除设置

注意：只有应用这些设置之后生成的令牌会受到影响；这些设置不适用于之前生成的令牌。

不符合 RFC 标准的行为

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