<ph type="x-smartling-placeholder"></ph>
您正在查看 Apigee Edge 文档。
转到
Apigee X 文档。 信息
内容
获取访问令牌属性、刷新令牌、授权代码和客户端应用属性,并使用这些属性的值填充变量。
当您需要根据令牌或身份验证代码中的值配置动态条件行为时,此政策很有用。每当发生令牌验证时,都会使用填充令牌属性的值自动填充变量。但是,如果未发生令牌验证,您可以使用此功能用令牌的属性值明确填充变量。另请参阅自定义令牌和授权代码。
您传递给此政策的访问令牌必须有效,否则政策将抛出 invalid_access_token
错误。
示例
以下示例使用“获取 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 |
政策的内部名称。 (可选)使用 |
不适用 | 必填 |
continueOnError |
设置为 设置为 |
false | 可选 |
enabled |
设置为 设为 |
是 | 可选 |
async |
此特性已弃用。 |
false | 已弃用 |
<DisplayName> 元素
除了用于 name
属性之外,还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
<DisplayName>Policy Display Name</DisplayName>
默认 |
不适用 如果省略此元素,则会使用政策的 |
---|---|
状态 | 可选 |
类型 | 字符串 |
<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 提供了政策架构作为参考。
错误参考信息
本部分介绍此政策触发错误时返回的错误代码和错误消息,以及 Edge 设置的故障变量。 在开发故障规则以处理故障时,请务必了解此信息。如需了解详情,请参阅您需要了解的有关政策错误的信息和处理故障。
运行时错误
政策执行时可能会发生这些错误。 下面显示的错误名称是在发生错误时分配给 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 | 如需了解如何排查此错误,请参阅此 Apigee 社区帖子。 |
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>