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

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

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

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

默认

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

不适用

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

状态可选

类型字符串

<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 提供了政策架构作为参考。

错误参考信息

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes. The error names shown below are the strings that are assigned to the fault.name variable when an error occurs. See the Fault variables section below for more details.

Fault code	HTTP status	Cause
`steps.oauth.v2.access_token_expired`	`500`	The access token sent to the policy is expired.
`steps.oauth.v2.authorization_code_expired`	`500`	The authorization code sent to the policy is expired.
`steps.oauth.v2.invalid_access_token`	`500`	The access token sent to the policy is invalid.
`steps.oauth.v2.invalid_client-invalid_client_id`	`500`	The client ID sent to the policy is invalid.
`steps.oauth.v2.invalid_refresh_token`	`500`	The refresh token sent to the policy is invalid.
`steps.oauth.v2.invalid_request-authorization_code_invalid`	`500`	The authorization code sent to the policy is invalid.
`steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound`	401	Please see Oauth2.0 Access Token Verification throws "Invalid API call as no apiproduct match found" error for information about troubleshooting this error.
`steps.oauth.v2.refresh_token_expired`	`500`	The refresh token sent to the policy is expired.

Deployment errors

Refer to the message reported in the UI for information about deployment errors.

Fault variables

These variables are set when this policy triggers an error at runtime.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "IPDeniedAccess"`
`oauthV2.policy_name.failed`	`policy_name` is the user-specified name of the policy that threw the fault.	`oauthV2.GetTokenInfo.failed = true`
`oauthV2.policy_name.fault.name`	`policy_name` is the user-specified name of the policy that threw the fault.	`oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id`
`oauthV2.policy_name.fault.cause`	`policy_name` is the user-specified name of the policy that threw the fault.	`oauthV2.GetTokenInfo.cause = ClientID is Invalid`

Example error response

{  
   "fault":{  
      "faultstring":"ClientId is Invalid",
      "detail":{  
         "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
      }
   }
}

Example fault rule

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