SetOAuthV2Info 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

政策图标

内容

可让您添加或更新与访问令牌关联的自定义属性。自定义属性可能包含部门名称、客户 ID 或会话标识符等内容。另请参阅自定义令牌和授权代码。

您只能添加或修改自定义属性。您无法使用此政策更改 scope、status、expires_in、developer_email、client_id、org_name 或 refresh_count 等字段。如果属性已经存在，则此政策会对其进行更新。如果不存在，则政策会添加此属性。引用的访问令牌必须有效且处于已批准状态。

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

示例

基本示例

以下是用于更新 OAuth 2.0 访问令牌的政策示例。以下示例通过查找名为 access_token 的查询参数来查找请求消息中的访问令牌。当客户端应用呈现访问令牌时，以下政策会在查询参数中查找访问令牌。然后，它会更新访问令牌的配置文件。它会将名为 department.id 的自定义属性添加到配置文件中。

<SetOAuthV2Info name="SetOAuthV2Info"> 
  <AccessToken ref="request.queryparam.access_token"></AccessToken>
  <Attributes>
    <Attribute name="department.id" ref="request.queryparam.department_id"></Attribute>
  </Attributes>
</SetOAuthV2Info>

元素参考

元素参考描述了 SetOAuthV2 政策的元素和属性。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SetOAuthV2Info async="false" continueOnError="false" enabled="true" name="SetOAuthV2Info-1">    
    <DisplayName>Set OAuth v2.0 Info 1</DisplayName>
    <AccessToken ref={some-variable}></AccessToken>
    <Attributes/>
</SetOAuthV2Info>
</xml>

<SetOAuthV2Info> 属性

<SetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Set-OAuth-v20-Info-1">

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

属性 说明 默认 Presence
name

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

（可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

 不适用 必需
continueOnError

设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。

设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅：

 false 可选
enabled

设置为 true 可强制执行政策。

设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。

 true 可选
async

此特性已弃用。

 false 已弃用

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>
默认

不适用

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

<AccessToken> 元素

识别访问令牌所在位置的变量。例如，如果将访问令牌作为查询参数附加到请求消息，请指定 request.queryparam.access_token。您可以使用引用令牌的任何有效变量。或者，传入字面令牌字符串（罕见大小写）。

 <AccessToken ref="request.queryparam.access_token"></AccessToken>
默认： 不适用
状态： 需要
类型： 字符串

属性

属性 说明 默认值 状态
ref

访问令牌变量。通常从流变量检索。

 不适用 可选

<Attributes> 元素

访问令牌配置文件中将要修改或扩充的一组属性。

默认： 不适用
状态： 需要
类型： 不适用

<Attributes>/<Attribute> 元素

要更新的单个属性。

name 属性用于识别要更新的访问令牌配置文件的自定义属性。此示例展示了如何使用引用的变量值和静态值。

  <Attributes>
    <Attribute name="department.id" ref="request.queryparam.department_id"></Attribute>
    <Attribute name="foo">bar</Attribute>
  </Attributes>
默认： 不适用
状态： 可选
类型： 不适用

属性

属性 说明 默认值 状态
name 要添加或更改的配置文件属性的名称。 不适用
ref

要分配给配置文件属性的值。

 不适用 可选

流变量

成功后，系统将设置以下流变量：

  • oauthv2accesstoken.{policyName}.access_token
  • oauthv2accesstoken.{policyName}.client_id
  • oauthv2accesstoken.{policyName}.refresh_count
  • oauthv2accesstoken.{policyName}.organization_name
  • oauthv2accesstoken.{policyName}.expires_in //--in seconds
  • oauthv2accesstoken.{policyName}.refresh_token_expires_in //--in seconds
  • oauthv2accesstoken.{policyName}.issued_at
  • oauthv2accesstoken.{policyName}.status
  • oauthv2accesstoken.{policyName}.api_product_list
  • oauthv2accesstoken.{policyName}.token_type
  • oauthv2accesstoken.{policyName}.{custom_attribute_name}

架构

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

错误参考信息

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

运行时错误

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

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

部署错误

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

故障变量

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

变量 地点 示例
fault.name="fault_name" fault_name 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。 fault.name = "invalid_access_token"
oauthV2.policy_name.failed policy_name 是抛出故障的政策的用户指定名称。 oauthV2.SetTokenInfo.failed = true
oauthV2.policy_name.fault.name policy_name 是抛出故障的政策的用户指定名称。 oauthV2.SetTokenInfo.fault.name = invalid_access_token
oauthv2.policy_name.fault.cause policy_name 是抛出故障的政策的用户指定名称。 oauthV2.SetTokenInfo.cause = Invalid Access Token

错误响应示例

{
  "fault": {
    "faultstring": "Invalid Access Token",
    "detail": {
      "errorcode": "keymanagement.service.invalid_access_token"
    }
  }
}

故障规则示例

<FaultRule name=SetOAuthV2Info Faults">
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

相关主题