GetOAuthV2Info 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

内容

获取访问令牌属性、刷新令牌、授权代码和客户端应用属性，并使用这些属性的值填充变量。

当您需要根据令牌或身份验证代码中的值配置动态条件行为时，此政策很有用。每当发生令牌验证时，都会使用填充令牌属性的值自动填充变量。但是，如果未发生令牌验证，您可以使用此功能用令牌的属性值明确填充变量。另请参阅自定义令牌和授权代码。

您传递给此政策的访问令牌必须有效，否则政策将抛出 invalid_access_token 错误。

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

示例

以下示例使用“获取 OAuth V2 信息”政策检索有关 OAuth2 工作流的各个组件的信息，然后在代码中访问该信息。

访问令牌

如需获取访问令牌的引用，请在政策中使用 <AccessToken> 元素。

以下示例可在名为“access_token”的查询参数中找到访问令牌（实际实现细节由您决定）：

<GetOAuthV2Info name="MyTokenAttrsPolicy">
  <AccessToken ref="request.queryparam.access_token"></AccessToken>
</GetOAuthV2Info>

给定访问令牌，该政策会查找令牌的配置文件，并使用配置文件数据填充一组变量。

然后，您可以使用 JavaScript 或其他方式访问该变量。以下示例使用 JavaScript 检索与访问令牌关联的范围：

var scope = context.getVariable('oauthv2accesstoken.MyTokenAttrsPolicy.scope');

请注意，如要在代码中访问这些变量，必须为其添加“oauthv2accesstoken”前缀。如需查看可通过访问令牌获取的变量的完整列表，请参阅访问令牌变量。

Auth 代码

如需获取授权代码属性，请在政策中使用 <AuthorizationCode> 元素。

以下示例可在名为“code”的表单参数中找到访问令牌（实际实现情况由您确定）：

<GetOAuthV2Info name="MyAuthCodeAttrsPolicy">
  <AuthorizationCode ref="request.formparam.code"></AuthorizationCode>
</GetOAuthV2Info>

对于给定 Auth 代码，该政策将查找代码的信息，并使用 Auth 代码数据填充一组变量。

然后，您可以使用 JavaScript 或其他方式访问该变量。以下示例使用 JavaScript 检索与授权代码关联的自定义属性：

var attr = context.getVariable('oauthv2authcode.MyAuthCodeAttrsPolicy.custom_attribute_name');

请注意，如要在代码中访问这些变量，必须为其添加“oauthv2authcode”前缀。如需查看可通过 Auth 代码获取的变量的完整列表，请参阅授权代码变量。

刷新令牌

如需获取刷新令牌属性，请在政策中使用 <RefreshToken> 元素。

以下示例可在名为“refresh_token”的查询参数中找到访问令牌（实际实现细节由您决定）：

<GetOAuthV2Info name="MyRefreshTokenAttrsPolicy">
  <RefreshToken ref="request.queryparam.refresh_token"/>
</GetOAuthV2Info>

对于给定刷新令牌，该政策将查找刷新令牌的相关信息，并使用刷新令牌数据填充一组变量。

然后，您可以使用 JavaScript 或其他方式访问这些变量。以下示例使用 JavaScript 检索与刷新令牌关联的自定义属性：

var attr = context.getVariable('oauthv2refreshtoken.MyRefreshTokenAttrsPolicy.accesstoken.custom_attribute_name');

请注意，如要访问代码中的变量，必须为其添加“oauthv2refreshtoken”前缀。如需查看可通过刷新令牌获取的变量的完整列表，请参阅刷新令牌变量。

静态

在极少数情况下，您可能需要获取静态配置令牌的（无法通过变量访问的令牌）配置文件。您可以通过以元素的形式提供访问令牌的值来实现此目的。

<GetOAuthV2Info name="GetTokenAttributes">
  <AccessToken>shTUmeI1geSKin0TODcGLXBNe9vp</AccessToken>
</GetOAuthV2Info>

您还可以使用所有其他令牌类型（客户端 ID、授权代码和刷新令牌）执行此操作。

客户端 ID

此示例展示了如何使用客户端 ID 检索有关客户端应用的信息。在执行时，该政策会使用客户端信息填充一组变量。在本例中，该政策可在名为 client_id 的查询参数中找到客户端 ID。给定客户端 ID，该政策会查找客户端的配置文件，并使用配置文件数据填充一组变量。该变量的前缀为 oauthv2client.

<GetOAuthV2Info name="GetClientAttributes">
  <ClientId ref="request.queryparam.client_id"></ClientId>
</GetOAuthV2Info>

然后，您可以使用 JavaScript 或其他方式访问该变量。例如，如要使用 JavaScript 获取与客户端应用关联的开发者应用名称和开发者电子邮件地址，请执行以下操作：

context.getVariable("oauthv2client.GetClientAttributes.developer.email");
context.getVariable("oauthv2client.GetClientAttributes.developer.app.name");

元素参考

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="GetOAuthV2Info-1"
    <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
    <AccessToken ref="variable"></AccessToken>
    <AuthorizationCode ref="variable"></AuthorizationCode>
    <ClientId ref="variable"></ClientId>
    <RefreshToken ref="variable"></RefreshToken>
</GetOAuthV2Info>

<GetOAuthV2Info> 属性

<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Get-OAuth-v20-Info-1">

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

属性	说明	默认	Presence
`name`	政策的内部名称。`name` 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。（可选）使用 `<DisplayName>` 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。	不适用	必需
`continueOnError`	设置为 `false` 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 `true`，即使在政策失败后，仍可以继续执行流。另请参阅：故障规则仅在错误状态下触发（关于 continueOnError）处理当前流中的故障	false	可选
`enabled`	设置为 `true` 可强制执行政策。设为 `false` 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。	true	可选
`async`	此特性已弃用。	false	已弃用

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

默认

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

不适用

如果省略此元素，则会使用政策的 name 属性的值。

Presence 可选

类型字符串

<AccessToken> 元素

检索访问令牌的配置文件。您可以传入一个包含访问令牌字符串或字面量令牌字符串的变量（罕见情况下）。在此示例中，从请求中传递的查询参数中检索访问令牌。如果要返回已撤销令牌或过期令牌的信息，请使用<IgnoreAccessTokenStatus>元素。

<AccessToken ref="request.queryparam.access_token"></AccessToken>

默认：	request.formparam.access_token（x-www-form-urlencoded 并在请求正文中指定）
状态：	可选
类型：	字符串
有效值：	包含访问令牌字符串或字面量字符串的流变量。

<AuthorizationCode> 元素

检索授权代码的配置文件。您可以传入包含 Auth 代码字符串或字面量令牌字符串（罕见情况）的变量。在此示例中，系统将从请求中传递的查询参数中检索 Auth 代码。如需查看此操作所填充的变量列表，请参阅“流变量”。

<AuthorizationCode ref="request.queryparam.authorization_code"></AuthorizationCode>

默认：	request.formparam.access_token（x-www-form-urlencoded 并在请求正文中指定）
状态：	可选
类型：	字符串
有效值：	包含 Auth 代码字符串或字面量字符串的流变量。

<ClientId> 元素

检索与客户端 ID 相关的信息。在此示例中，从请求中传递的查询参数中检索客户端 ID。如需查看此操作所填充的变量列表，请参阅“流变量”。

<ClientId ref="request.queryparam.client_id"></ClientId>

默认：	request.formparam.access_token（x-www-form-urlencoded 并在请求正文中指定）
状态：	可选
类型：	字符串
有效值：	包含 Auth 代码字符串或字面量字符串的流变量。

<IgnoreAccessTokenStatus> 元素

即使令牌已过期或被撤消，也会返回令牌信息。此元素只能与访问令牌一起使用。默认情况下，无论其他实体（例如刷新令牌和授权代码）的状态如何，系统都会返回其信息。

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

默认：	false
状态：	可选
类型：	布尔值
有效值：	true 或 false

<RefreshToken> 元素

检索刷新令牌的配置文件。您传入一个包含刷新令牌字符串或字面量令牌字符串（罕见情况）的变量。在此示例中，从请求中传递的查询参数中检索刷新令牌。如需查看此操作所填充的变量列表，请参阅“流变量”。

<RefreshToken ref="request.queryparam.refresh_token"></RefreshToken>

默认：	request.formparam.access_token（x-www-form-urlencoded 并在请求正文中指定）
状态：	可选
类型：	字符串
有效值：	包含刷新令牌字符串或字面量字符串的流变量。

流变量

GetOAuthV2Info 政策会填充这些变量，并且通常在需要配置文件数据，但尚未对其进行授权或验证的情况下使用。.

客户端 ID 变量

设置 ClientId 元素时，将填充这些变量：

oauthv2client.{policy_name}.client_id
oauthv2client.{policy_name}.client_secret
oauthv2client.{policy_name}.redirection_uris // Note the spelling -- 'redirection_uris'
oauthv2client.{policy_name}.developer.email
oauthv2client.{policy_name}.developer.app.name
oauthv2client.{policy_name}.developer.id
oauthv2client.{policy_name}.{developer_app_custom_attribute_name}

访问令牌变量

设置 AccessToken 元素时，将填充这些变量：

oauthv2accesstoken.{policy_name}.developer.id
oauthv2accesstoken.{policy_name}.developer.app.name
oauthv2accesstoken.{policy_name}.developer.app.id
oauthv2accesstoken.{policy_name}.developer.email

oauthv2accesstoken.{policy_name}.organization_name
oauthv2accesstoken.{policy_name}.api_product_list

oauthv2accesstoken.{policy_name}.access_token
oauthv2accesstoken.{policy_name}.scope
oauthv2accesstoken.{policy_name}.expires_in //in seconds
oauthv2accesstoken.{policy_name}.status
oauthv2accesstoken.{policy_name}.client_id
oauthv2accesstoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2accesstoken.{policy_name}.refresh_token
oauthv2accesstoken.{policy_name}.refresh_token_status
oauthv2accesstoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2accesstoken.{policy_name}.refresh_count
oauthv2accesstoken.{policy_name}.refresh_token_issued_at
oauthv2accesstoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

授权代码变量

设置 AuthorizationCode 元素时，将填充这些变量：

oauthv2authcode.{policy_name}.code
oauthv2authcode.{policy_name}.scope       
oauthv2authcode.{policy_name}.redirect_uri 
oauthv2authcode.{policy_name}.client_id
oauthv2authcode.{policy_name}.{auth_code_custom_attribute_name}

刷新令牌变量

设置 RefreshToken 元素时，将填充这些变量：

oauthv2refreshtoken.{policy_name}.developer.id
oauthv2refreshtoken.{policy_name}.developer.app.name
oauthv2refreshtoken.{policy_name}.developer.app.id
oauthv2refreshtoken.{policy_name}.developer.email
oauthv2refreshtoken.{policy_name}.organization_name
oauthv2refreshtoken.{policy_name}.api_product_list

oauthv2refreshtoken.{policy_name}.access_token
oauthv2refreshtoken.{policy_name}.scope
oauthv2refreshtoken.{policy_name}.expires_in //in seconds

oauthv2refreshtoken.{policy_name}.status
oauthv2refreshtoken.{policy_name}.client_id
oauthv2refreshtoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2refreshtoken.{policy_name}.refresh_token
oauthv2refreshtoken.{policy_name}.refresh_token_status
oauthv2refreshtoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2refreshtoken.{policy_name}.refresh_count
oauthv2refreshtoken.{policy_name}.refresh_token_issued_at
oauthv2refreshtoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

架构

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

错误参考信息

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

运行时错误

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

故障代码	HTTP 状态	原因
`steps.oauth.v2.access_token_expired`	`500`	发送到该政策的访问令牌已过期。
`steps.oauth.v2.authorization_code_expired`	`500`	发送到该政策的授权代码已过期。
`steps.oauth.v2.invalid_access_token`	`500`	发送到该政策的访问令牌无效。
`steps.oauth.v2.invalid_client-invalid_client_id`	`500`	发送到该政策的客户 ID 无效。
`steps.oauth.v2.invalid_refresh_token`	`500`	发送到该政策的刷新令牌无效。
`steps.oauth.v2.invalid_request-authorization_code_invalid`	`500`	发送到该政策的授权代码无效。
`steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound`	401	如需了解有关如何排查此错误的信息，请参阅 Oauth2.0 访问令牌验证抛出的：“由于未找到 apiproduct 匹配项，API 调用无效”的错误。
`steps.oauth.v2.refresh_token_expired`	`500`	发送到该政策的刷新令牌已过期。

部署错误

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

故障变量

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

变量	位置	示例
`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":"ClientId is Invalid",
      "detail":{  
         "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
      }
   }
}

故障规则示例

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientIdResponse</Name>
    </Step>
    <Condition>(fault.name = "invalid_client-invalid_client_id")</Condition>
</FaultRule>