此页面由 Cloud Translation API 翻译。

OAuthV2 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。信息

内容

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

注意：OAuthV2 政策返回某些不符合 RFC 规范的响应元素。例如，政策会返回令牌属性 "token_type":"BearerToken"，但符合条件的令牌属性应为 "token_type":"Bearer"。如需详细了解这些不符合规定的响应元素，请参阅不符合 RFC 规范的行为。

提示：如需详细了解 Apigee Edge 上的 OAuth，请参阅 OAuth 首页。它提供了资源、示例、视频等内容的链接。有关详情，请参阅高级 GitHub 上的 OAuth 示例，很好地演示了此政策在工作中应用。

示例

VerifyAccessToken

此 OAuthV2 政策配置（包含 VerifyAccessToken 操作）会验证提交到 Apigee Edge 的访问令牌有效。触发此政策操作后，Edge 在请求中查找有效的访问令牌。如果访问令牌有效，则允许该请求继续。如果无效，所有处理都将停止，并在响应中返回错误。

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

注意：仅支持 OAuth 2.0 不记名令牌。不支持消息身份验证代码 (MAC) 令牌。

例如：

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

默认情况下，Edge 接受 Authorization 标头中具有 Bearer 前缀。您可以使用 <AccessToken> 元素更改此默认设置。

GenerateAccessToken

生成访问令牌

如需查看如何针对每种支持的授权类型请求访问令牌，请参阅请求访问令牌和授权代码。本主题包括以下操作的示例：

GenerateAuthorizationCode

生成授权代码

如需查看有关如何请求授权代码，请参阅请求授权代码。

RefreshAccessToken

刷新访问令牌

如需了解如何使用刷新令牌请求访问令牌，请参阅刷新访问令牌。

响应流令牌

生成响应流访问令牌

有时，您可能需要在响应流中生成访问令牌。例如，您可以这样做，以回应后端服务中的一些自定义验证。在此示例中，用例需要访问令牌和刷新令牌，而非隐式授权类型。在这种情况下，我们将使用密码授权类型来生成令牌。如您所见，实现此操作的技巧是传入带有 JavaScript 政策的授权请求标头。

首先，让我们来看看示例政策：

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

如果您将此政策放入响应流，那么即使在政策中指定正确的登录参数，它也会失败并显示“401 未经授权”错误。要解决此问题，您需要设置授权请求标头。

授权标头必须包含具有 Base64 编码的 client_id:client_secret 的基本访问方案。

您可以添加此标头，并将 JavaScript 政策置于 OAuthV2 政策前，就像这样。“local_clientid”和“local_secret”变量必须预先设置并可以在流中使用：

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

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

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

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

默认

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

不适用

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

状态可选

类型字符串

<AccessToken> 元素

<AccessToken>request.header.access_token</AccessToken>

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

指定了 <AccessToken>request.header.access_token</AccessToken> 的示例：

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

<AccessToken>request.queryparam.access_token</AccessToken> 为指定：

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

默认：	不适用
状态：	可选
类型：	字符串
与操作配合使用：	VerifyAccessToken

<AccessTokenPrefix> 元素

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

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

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

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

默认：	不记名
状态：	可选
类型：	字符串
有效值：	不记名
与操作配合使用：	VerifyAccessToken

<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 访问令牌。

默认：	不适用
状态：	可选
类型：	字符串
有效值：	运行时可访问政策的任何流变量。
与授权类型配合使用：	authorization_code 隐式密码 client_credentials

<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 政策手动提取您不想在响应中看到的任何自定义属性。

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

默认：	`N/A`
状态：	可选
有效值：	`name` -属性名称 `ref` - 属性名称。可能来自流变量。 `display` - （可选）可让您指定是否在响应中显示自定义属性。如果为 `true`，则响应中会出现自定义属性（如果还启用 `GenerateResponse`）。如果为 `false`，则响应中不会包含自定义属性。默认值为 `true`。请参阅在响应中显示或隐藏自定义属性。
与授权类型配合使用：	authorization_code 隐式密码 client_credentials refresh_token 也可与 GenerateAuthorizationCode 操作配合使用。

<ClientId> 元素

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

在很多情况下，客户端应用必须将客户端 ID 发送到授权服务器。这个元素指定 Edge 应在何处查找客户端 ID。您可以设置的唯一有效位置是默认位置，即流变量 request.formparam.client_id。不支持将 ClientId 设置为任何其他变量。另请参阅请求访问令牌和授权代码。

默认：	request.formparam.client_id（x www-www-form-urlencoded 并在请求正文中指定）
状态：	可选
类型：	字符串
有效值：	流变量：`request.formparam.client_id`
与授权类型配合使用：	authorization_code 密码隐式 client_credentials 也可与 GenerateAuthorizationCode 操作配合使用。

<Code> 元素

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

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

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

默认：	request.formparam.code（x-www-form-urlencoded，并在请求正文中指定）
状态：	可选
类型：	字符串
有效值：	运行时可访问政策的任何流变量
与授权类型配合使用：	authorization_code

<ExpiresIn> 元素

<ExpiresIn>10000</ExpiresIn>

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

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

借助适用于公有云的 Apigee Edge，Edge 可保持在实体被访问后，在缓存中保留至少 180 秒。

OAuth 访问令牌。这意味着，撤销的令牌在最多 30 秒的时间内分钟，直到其缓存限制到期。
密钥管理服务 (KMS) 实体（应用、开发者、API 产品）。
OAuth 令牌和 KMS 实体的自定义属性。

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

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

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

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

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

通过编辑器打开 message-processor.properties 文件。如果该文件不存在，请创建该文件：
```
vi /opt/apigee/customer/application/message-processor.properties
```

根据需要设置属性：

conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

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

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

重启消息处理器。

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

默认：	如果未指定，则系统会应用在系统级别配置的默认值。
状态：	可选
类型：	整数
有效值：	任何非零正整数。指定以毫秒为单位表示的过期时间。虽然此元素的值以毫秒为单位，但令牌的 `expires_in` 属性和 `expires_in` 流变量中设置的值以秒为单位。根据 OAuth 访问令牌的过期期限，-1 将到期。注意：指定任何其他负整数或零会导致部署错误。另请参阅反模式：设置 OAuth 令牌的较长有效期。
与授权类型配合使用：	authorization_code 隐式密码 client_credentials refresh_token 也可与 GenerateAuthorizationCode 操作配合使用。

注意：如果将 ExpiresIn 设置为 -1，您会在生成的令牌中看到以下过期时间值：

"expires_in" :
  "0"

。

<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 会验证 client_id 和 client_secret 与 Apigee Edge 授权存储区相当。如果您要使用第三方 OAuth 令牌，请使用此元素。要详细了解如何使用此元素，请参阅使用第三方 OAuth 令牌。

默认：	false
状态：	可选
类型：	布尔值
有效值：	true 或 false
与授权类型配合使用：	authorization_code 密码 client_credentials

<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 在响应中以秒为单位表示。

默认：	false
状态：	可选
类型：	字符串
有效值：	true 或 false
与授权类型配合使用：	隐式密码 client_credentials refresh_token 也可与 GenerateAuthorizationCode 操作配合使用。

<GenerateErrorResponse> 元素

<GenerateErrorResponse enabled='true'/>

如果设为 true，则如果 ContinueOnError 属性设置为 true，则政策将生成响应并返回响应。如果为 false（默认值），则不会发送响应。相反，一组流变量使用与政策的函数相关的值填充。

默认：	false
状态：	可选
类型：	字符串
有效值：	true 或 false
与授权类型配合使用：	隐式密码 client_credentials refresh_token 也可与 GenerateAuthorizationCode 操作配合使用。

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

告知政策在何处找到在请求中传递的授权类型参数。根据 OAuth 2.0 规范，必须向请求类型提供访问令牌和授权代码请求。变量可以是标头、查询参数或表单参数（默认）。

例如，request.queryparam.grant_type 表示密码应以查询参数的形式显示，例如 ?grant_type=password。例如，要在 HTTP 标头中请求授权类型，请将此值设置为 request.header.grant_type。另请参阅请求访问令牌和授权代码。

默认：	request.formparam.grant_type（x-www-form-urlencoded，并在请求正文中指定）
状态：	可选
类型：	字符串
有效值：	如上所述的变量。
与授权类型配合使用：	authorization_code 密码隐式 client_credentials refresh_token

<Operation> 元素

<Operation>GenerateAuthorizationCode</Operation>

OAuth 2.0 操作由此政策执行。

默认：	如果未指定 `<Operation>`，则 Edge 会查找 `<SupportedGrantTypes>`。只有针对这些授权类型的操作才会成功。换句话说，如果您在 `<SupportedGrantTypes>` 列表中指定了 `<GrantType>`，则可以省略 `<Operation>`。如果 `<Operation>` 和 `<SupportedGrantTypes>` 均未指定，则默认授权类型是 authorization_code。也就是说，授权代码授权类型的请求将成功，但其他所有类型的请求将失败。
状态：	可选
类型：	字符串
有效值：	`GenerateAccessToken` - 生成访问令牌。另请参阅请求访问令牌和授权代码。 `GenerateAccessTokenImplicitGrant` - 为隐式授权类型生成访问令牌。另请参阅请求访问令牌和授权代码。 `GenerateAuthorizationCode` - 生成授权代码。与授权代码授权类型配合使用。另请参阅请求访问令牌和授权代码。 `RefreshAccessToken` - 用刷新令牌换取新的访问令牌。另请参阅请求访问令牌和授权代码。 `VerifyAccessToken` - 验证请求中发送的访问令牌是否有效。请参阅上面的 VerifyAccessToken 示例和验证访问令牌”。 `InvalidateToken` - 撤消访问令牌。令牌撤消后，客户端将无法使用该令牌调用受保护的 API。另请参阅批准和撤消访问令牌。 `ValidateToken` - 恢复或“批准”之前撤消的访问令牌。另请参阅批准和撤消访问令牌。

<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 开发者负责检索值请求并将其发送到身份提供商。

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

默认：	request.formparam.password（x-www-form-urlencoded，并在请求正文中指定）
状态：	可选
类型：	字符串
有效值：	运行时任何政策可用的流变量。
与授权类型配合使用：	密码

<RedirectUri> 元素

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

指定 Edge 应在哪个位置查找 redirect_uri 参数，请求。

关于重定向 URI

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

（必需）如果使用与请求的客户端密钥关联的开发者应用注册回调网址，且请求中显示 redirect_uri，则这两个网址必须完全匹配。如果它们不匹配，则返回错误。相关信息如需了解如何在 Edge 上注册开发者应用并指定回调网址，请参阅注册应用和管理 API 密钥。
<ph type="x-smartling-placeholder">
</ph> 注意：为确保 Edge 检查“回调网址”之间是否完全匹配和 “redirect_uri”（而不是前向匹配），请在组织：features.isStrictOAuthUriValidation = true。默认值为 false（前向匹配）。
如果您是云客户，请与 Apigee Edge 支持团队联系，以启用属性。如果您是适用于私有云的 Apigee Edge 客户，请使用以下 API PUT 调用（带有系统管理员凭据）。
```
curl -u email:password -X PUT -H "Content-type:application/xml" http://host:port/v1/o/{myorg} -d \
"<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isStrictOAuthUriValidation">true</Property>
        
    </Properties>
</Organization>"
```
警告：使用 API 调用更新组织时，请务必在载荷中包含所有现有组织属性。否则只有您设置的属性会覆盖所有现有的组织属性这场通话。
（可选）如果回调网址已注册，但缺少 redirect_uri Edge 会重定向到已注册的回调网址。
（必需）如果未注册回调网址，则需要 redirect_uri。请注意，在这种情况下，Edge 将接受任意网址。此案例可能会出现安全问题，因此应仅用于受信任的客户端应用。如果客户端应用不受信任，最佳做法是始终注册回调网址。

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

默认：	request.formparam.redirect_uri（x-www-form-urlencoded 并在请求正文中指定）
状态：	可选
类型：	字符串
有效值：	运行时可访问政策的任何流变量
与授权类型配合使用：	authorization_code 隐式与 GenerateAuthorizationCode 操作配合使用。

<RefreshToken> 元素

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

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

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

默认：	request.formparam.refresh_token（x www-www-form-urlencoded 并在请求正文中指定）
状态：	可选
类型：	字符串
有效值：	运行时可访问政策的任何流变量
与授权类型配合使用：	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 属性设置。如需设置此属性，请执行以下操作：

通过编辑器打开 message-processor.properties 文件。如果该文件不存在，请创建该文件：
```
vi /opt/apigee/customer/application/message-processor.properties
```

根据需要设置属性：

conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

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

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

重启消息处理器。

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

默认：	63072000000 毫秒（2 年）（2024 年 8 月 5 日生效）
状态：	可选
类型：	整数
有效值：	任何非零正整数。指定过期时间以毫秒为单位。根据 OAuth 刷新令牌的过期期限，-1 将到期。注意：指定任何其他负整数或零会导致部署错误。另请参阅反模式：设置 OAuth 令牌的较长有效期。
与授权类型配合使用：	authorization_code 密码 refresh_token

<ResponseType> 元素

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

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

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

默认：	request.formparam.response_type（x-www-form-urlencoded，并在请求正文中指定）
状态：	可选。如果您希望替换默认行为，请使用此元素。
类型：	字符串
有效值：	`code`（适用于授权代码授权类型）或 `token`（适用于隐式授权类型）
与授权类型配合使用：	隐式与 GenerateAuthorizationCode 操作配合使用。

<ReuseRefreshToken> 元素

<ReuseRefreshToken>true</ReuseRefreshToken>

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

默认：	`false`
状态：	可选
类型：	布尔值
有效值：	`true` 或 `false`
与授权类型配合使用：	refresh_token

<Scope> 元素

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

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

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

<Scope>A B</Scope>

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

默认：	无范围
状态：	可选
类型：	字符串
有效值：	与生成*政策配合使用时，则为流变量。与 VerifyAccessToken 配合使用时，空格分隔的范围名称列表（字符串）。
与授权类型配合使用：	authorization_code 隐式密码 client_credentials 也可用于 GenerateAuthorizationCode 和 VerifyAccessToken 操作。

<State> 元素

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

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

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

默认：	无状态
状态：	可选
类型：	字符串
有效值：	运行时可访问政策的任何流变量
与授权类型配合使用：	全部也可与 GenerateAuthorizationCode 操作配合使用

<StoreToken> 元素

 <StoreToken>true</StoreToken>

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

默认：	false
状态：	可选
类型：	布尔值
有效值：	true 或 false
与授权类型配合使用：	authorization_code 密码 client_credentials

<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 参数的值与某个受支持的授权类型匹配）。

默认：	authorization _code 和隐式
状态：	必填
类型：	字符串
有效值：	client_credentials authorization_code 密码隐式

<Tokens>/<Token> 元素

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

<UserName> 元素

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

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

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

默认：	request.formparam.username（x-www-form-urlencoded，并在请求正文中指定）
状态：	可选
类型：	字符串
有效值：	任何变量设置。
与授权类型配合使用：	密码

验证访问令牌

为 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>
AccessToken	访问令牌防止位置的变量。例如：`request.queryparam.accesstoken`。默认情况下，根据 OAuth 2.0 规范，访问令牌应通过授权 HTTP 标头中的应用显示。如果访问令牌需在非标准位置（例如查询参数）或 HTTP 标头（名称并非授权）中显示，请使用此设置。

以空格分隔的范围列表。如果访问令牌中至少有一个列出的范围，则验证会成功。例如，以下政策将检查访问令牌，确保其中至少包含一个列出的范围。如果出现读或写，则验证成功。

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

AccessToken 访问令牌防止位置的变量。例如：request.queryparam.accesstoken。默认情况下，根据 OAuth 2.0 规范，访问令牌应通过授权 HTTP 标头中的应用显示。如果访问令牌需在非标准位置（例如查询参数）或 HTTP 标头（名称并非授权）中显示，请使用此设置。

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

指定请求变量位置

对于每个授权类型，政策会对请求消息中的位置或必需信息做出假设。这些假设基于 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 政策读取任何这些变量，并在流中稍后根据需要使用。这些变量还可用于调试。

注意：如果 API 产品配置了有效环境、代理和 API 资源（派生自 proxy.pathsuffix），API 产品变量将自动填充。无需明确设置 flow.resource.name 变量。

如果 API 产品未配置有效环境和 API 代理，则必须明确设置 flow.resource.name，以填充流中的 API 产品变量。如需详细了解产品配置，请参阅使用 Edge 管理 API 发布 API。

令牌专用变量

变量	说明
`organization_name`	执行代理的组织名称。
`developer.id`	与已注册客户端应用关联的开发者 ID。
`developer.app.name`	与已注册客户端应用关联的开发者名称。
`client_id`	已注册客户端应用的客户端 ID。
`grant_type`	与请求关联的授权类型。
`token_type`	与请求关联的令牌类型。
`access_token`	正在验证的访问令牌。
`accesstoken.{custom_attribute}`	访问令牌中已命名的自定义属性。
`issued_at`	访问令牌发放日期以 Unix 计时原点表达，以毫秒为单位。
`expires_in`	访问令牌的过期时间。以秒为单位表达。虽然 `ExpiresIn` 元素以毫秒为单位设置过期时间，但在令牌响应和流变量中，该值以秒为单位表达。
`status`	访问令牌的状态（例如已批准或已撤消）。
`scope`	与访问令牌关联的范围（如果有）。
`apiproduct.<custom_attribute_name>`	与已注册客户端应用关联的 API 产品的已命名自定义属性。
`apiproduct.name`	与已注册客户端应用关联的 API 产品的名称。
`revoke_reason`	（仅限 Apigee Hybrid）表示访问令牌被撤消的原因。值可以是 `REVOKED_BY_APP`、`REVOKED_BY_ENDUSER`、`REVOKED_BY_APP_ENDUSER` 或 `TOKEN_REVOKED`。

应用专用变量

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

变量	说明
`app.name`
`app.id`
`app.accessType`
`app.callbackUrl`
`app.status`	已批准或已撤消
`app.scopes`
`app.appFamily`
`app.apiproducts`
`app.appParentStatus`
`app.appType`	例如：开发者
`app.appParentId`
`app.created_by`
`app.created_at`
`app.last_modified_at`
`app.last_modified_by`
`app.{custom_attributes}`	已注册客户端应用的已命名自定义属性。

开发者专用变量

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

变量	说明
开发者专用变量
`developer.id`
`developer.userName`
`developer.firstName`
`developer.lastName`
`developer.email`
`developer.status`	活跃或非活跃
`developer.apps`
`developer.created_by`
`developer.created_at`
`developer.last_modified_at`
`developer.last_modified_by`
`developer.{custom_attributes}`	开发者的已命名自定义属性。

公司专用变量

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

变量	说明
`company.id`
`company.displayName`
`company.apps`
`company.appOwnerStatus`
`company.created_by`
`company.created_at`
`company.last_modified_at`
`company.last_modified_by`
`company.{custom_attributes}`	公司的已命名自定义属性。

GenerateAuthorizationCode 操作

当 GenerateAuthorizationCode 操作成功执行时，将设置这些变量：

前缀： oauthv2authcode.{policy_name}.{variable_name}

示例： oauthv2authcode.GenerateCodePolicy.code

变量	说明
`code`	政策执行时生成的授权代码。
`redirect_uri`	与已注册客户端应用关联的重定向 URI。
`scope`	在客户端请求中传递的可选 OAuth 范围。
`client_id`	客户端请求中传递的客户端 ID。

GenerateAccessToken 和 RefreshAccessToken 操作

当 GenerateAccessToken 和 RefreshAccessToken 操作成功执行时，将设置这些变量。请注意，刷新令牌变量不适用于客户端凭据授权类型流。

前缀： oauthv2accesstoken.{policy_name}.{variable_name}

示例： oauthv2accesstoken.GenerateTokenPolicy.access_token

变量名称	说明
`access_token`	生成的访问令牌。
`client_id`	与此令牌关联的开发者应用的客户端 ID。
`expires_in`	令牌的到期值。如需了解详情，请参阅 <ExpiresIn> 元素。请注意，在响应中，expires_in 以秒为单位表示。
`scope`	为令牌配置的可用范围列表。请参阅使用 OAuth2 范围。
`status`	`approved` 或 `revoked`。
`token_type`	设置为 `BearerToken`。

`developer.email`	拥有与令牌关联的开发者应用的已注册开发者的电子邮件地址。
`organization_name`	执行代理的组织。
`api_product_list`	与令牌的相应开发者应用关联的产品列表。

`refresh_count`
`refresh_token`	生成的刷新令牌。请注意，系统不会为客户端凭据授权类型生成刷新令牌。
`refresh_token_expires_in`	刷新令牌的有效期（以秒为单位）。
`refresh_token_issued_at`	此时间值是相应的 32 位时间戳数量的字符串表示形式。例如，“2013 年 8 月 21 日星期三 19:16:47 世界协调时间 (UTC)”对应的时间戳值为 1377112607413。
`refresh_token_status`	`approved` 或 `revoked`。

GenerateAccessTokenImplicitGrant

当为隐式授权类型流成功执行 GenerateAccessTokenImplicit 操作时，将设置这些变量。

前缀： oauthv2accesstoken.{policy_name}.{variable_name}

示例： oauthv2accesstoken.RefreshTokenPolicy.access_token

变量	说明
`oauthv2accesstoken.access_token`	执行政策时生成的访问令牌。
`oauthv2accesstoken.{policy_name}.expires_in`	令牌的到期值（以秒为单位）。有关详情，请参阅 <ExpiresIn> 元素。

错误参考信息

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

运行时错误

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

故障代码	HTTP 状态	原因	由操作抛出
`steps.oauth.v2.access_token_expired`	401	访问令牌已过期。	VerifyAccessToken InvalidateToken
`steps.oauth.v2.access_token_not_approved`	401	访问令牌已被撤消。	VerifyAccessToken
`steps.oauth.v2.apiresource_doesnot_exist`	401	所请求的资源不存在与访问令牌关联的任何 API 产品。	VerifyAccessToken
`steps.oauth.v2.FailedToResolveAccessToken`	500	政策应在 `<AccessToken>` 元素中指定的变量中找到访问令牌，但无法解析该变量。	GenerateAccessToken
`steps.oauth.v2.FailedToResolveAuthorizationCode`	500	政策应在 `<Code>` 元素中指定的变量中找到授权代码，但无法解析该变量。	GenerateAuthorizationCode
`steps.oauth.v2.FailedToResolveClientId`	500	政策应在 `<ClientId>` 元素中指定的变量中找到客户端 ID，但无法解析该变量。	GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken
`steps.oauth.v2.FailedToResolveRefreshToken`	500	政策应在 `<RefreshToken>` 元素中指定的变量中找到刷新令牌，但无法解析该变量。	RefreshAccessToken
`steps.oauth.v2.FailedToResolveToken`	500	政策应在 `<Tokens>` 元素中指定的变量中找到令牌，但无法解析该变量。	ValidateToken InvalidateToken
`steps.oauth.v2.InsufficientScope`	403	请求中提供的访问令牌的范围与验证访问令牌政策中指定的范围不匹配。要了解范围，请参阅使用 OAuth2 范围。	VerifyAccessToken
`steps.oauth.v2.invalid_access_token`	401	从客户端发送的访问令牌无效。	VerifyAccessToken
`steps.oauth.v2.invalid_client`	401	将政策的 `<GenerateResponse>` 属性设置为 true，且在请求中发送的客户端 ID 无效时，系统会返回此错误名称。检查确保您在使用与代理关联的开发者应用的正确客户端密钥和密钥值。这些值通常作为 Base64 编码的基本授权标头发送。注意：建议您更改现有故障规则条件，以捕获 `invalid_client` 和 `InvalidClientIdentifier` 名称。如需了解详情并查看示例，请参阅 16.09.21 版本说明。	GenerateAccessToken RefreshAccessToken
`steps.oauth.v2.invalid_request`	400	此错误名称用于多种不同类型的错误，通常适用于在请求中发送的丢失或不正确参数。如果将 `<GenerateResponse>` 设置为 `false`，则使用故障变量（如下所述）来检索错误的详细信息，例如故障名称和原因。	GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken
`steps.oauth.v2.InvalidAccessToken`	401	授权标头不包含“Bearer”一词，而这是必需的。例如：`Authorization: Bearer your_access_token`	VerifyAccessToken
`steps.oauth.v2.InvalidAPICallAsNo\ steps.oauth.v2.ApiProductMatchFound`	401	API 代理不在与访问令牌相关联的产品中。提示：确保与访问令牌关联的产品已正确配置。例如，如果在资源路径中使用通配符，请确保正确使用通配符。如需了解详情，请参阅创建 API 产品。另请参阅这篇 Apigee 社区博文，详细了解造成此错误的原因。	VerifyAccessToken
`steps.oauth.v2.InvalidClientIdentifier`	500	将政策的 `<GenerateResponse>` 属性设置为 false，且在请求中发送的客户端 ID 无效时，系统会返回此错误名称。检查确保您在使用与代理关联的开发者应用的正确客户端密钥和密钥值。这些值通常作为 Base64 编码的基本授权标头发送。注意：在这种情况下，此错误过去称为 `invalid_client`。建议您更改现有故障规则条件，以捕获 `invalid_client` 和 `InvalidClientIdentifier` 名称。如需了解详情并查看示例，请参阅 16.09.21 版本说明。	GenerateAccessToken RefreshAccessToken
`steps.oauth.v2.InvalidParameter`	500	政策必须指定访问令牌或授权代码，但不能同时指定这两者。	GenerateAuthorizationCode GenerateAccessTokenImplicitGrant
`steps.oauth.v2.InvalidTokenType`	500	`<Tokens>/<Token>` 元素要求您指定令牌类型（例如 `refreshtoken`）。如果客户端传递的类型不正确，则会抛出此错误。	ValidateToken InvalidateToken
`steps.oauth.v2.MissingParameter`	500	响应类型为 `token`，但未指定授权类型。	GenerateAuthorizationCode GenerateAccessTokenImplicitGrant
`steps.oauth.v2.UnSupportedGrantType`	500	客户端指定的授权类型不受政策支持（未在 <SupportedGrantTypes> 元素中列出）。注意：当前存在一个错误，即未正确抛出不支持的授权类型错误。如果发生不受支持的授权类型错误，则代理不会按预期进入错误流。	GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken

部署错误

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

错误名称	原因
`InvalidValueForExpiresIn`	对于 `<ExpiresIn>` 元素，有效值为正整数和 `-1`。
`InvalidValueForRefreshTokenExpiresIn`	对于 `<RefreshTokenExpiresIn>` 元素，有效值为正整数和 `-1`。
`InvalidGrantType`	在 `<SupportedGrantTypes>` 元素中指定的授权类型无效。请参阅政策参考，获取有效类型的列表。
`ExpiresInNotApplicableForOperation`	确保在 <Operations> 元素中指定的操作支持到期。例如，VerifyToken 操作不支持。
`RefreshTokenExpiresInNotApplicableForOperation`	确保在 <Operations> 元素中指定的操作支持刷新令牌到期。例如，VerifyToken 操作不支持。
`GrantTypesNotApplicableForOperation`	确保指定操作支持在 <SupportedGrantTypes> 中指定的授权类型。
`OperationRequired`	您必须使用 `<Operation>` 元素在此政策中指定操作。注意：如果缺少 `<Operation>` 元素，则界面会抛出架构验证错误。
`InvalidOperation`	您必须使用 `<Operation>` 元素在此政策中指定有效的操作。注意：如果 `<Operation>` 元素无效，则界面会抛出架构验证错误。
`TokenValueRequired`	您必须在 `<Tokens>` 元素中指定一个令牌 `<Token>` 值。

故障变量

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

注意：您可以使用这些变量来创建故障规则条件。如果在将 <GenerateResponse> 设置为 false 时出现错误，则会填充这些变量。如果 <GenerateResponse> 为 true，则在发生错误时，政策会立即向客户端返回响应 - 将跳过错误流，并且不会填充这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

变量	地点	示例
`fault.name="fault_name"`	`fault_name` 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。	`fault.name = "invalid_request"`
`oauthV2.policy_name.failed`	`policy_name` 是抛出故障的政策的用户指定名称。	`oauthV2.GenerateAccesstoken.failed = true`
`oauthV2.policy_name.fault.name`	`policy_name` 是抛出故障的政策的用户指定名称。	`oauthV2.GenerateAccesstoken.fault.name = invalid_request` 注意：对于 VerifyAccessToken 操作，故障名称包括此后缀：`keymanagement.service` 例如：`keymanagement.service.invalid_access_token`
`oauthV2.policy_name.fault.cause`	`policy_name` 是抛出故障的政策的用户指定名称。	`oauthV2.GenerateAccesstoken.cause = Required param : grant_type`

错误响应示例

如果 <GenerateResponse> 元素为 true，则会将这些响应发送回客户端。

注意：处理错误时，最佳做法是捕获错误响应的 errorcode 部分。不要依赖 faultstring 中的文本，因为它可能会发生变化。

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

如果您使用的是适用于私有云的 Edge，则可以通过设置组织属性。（在 3 天内完全清除过期令牌适用于适用于私有云的 Edge 版本 4.19.01 及更高版本。对于早期版本，默认完全清除间隔为 180 天）。

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

注意：只有在这些设置之后生成的令牌才会被纳入考量。都会受到影响；这些设置不适用于之前生成的令牌。

</ph> Private Cloud：

打开此文件进行编辑：

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

添加以下属性以设置在完全清除令牌之前等待的秒数之后：
```
conf_keymanagement_oauth.access.token.purge.after.seconds=<number of seconds>
```

重启消息处理器。例如：

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

如果访问令牌永不过期，则永远不会被完全清除。您可以设置令牌使用 <ExpiresIn> 和 <RefreshTokenExpiresIn> 属性。

正在更新完全清除操作 Edge Private Cloud 4.15.07 的设置

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

</ph> Private Cloud：

为 <ExpiresIn> 和 <RefreshTokenExpiresIn> 属性。值包含毫秒。例如：
```
<ExpiresIn>1000</ExpiresIn>
<RefreshTokenExpiresIn>10000</RefreshTokenExpiresIn>
```
重新部署代理。

使用此 API 更新贵组织的令牌完全清除属性：

POST https://<host-name>/v1/organizations/<org-name>

载荷：

<Organization name="AutomationOrganization"> 
 <Description>Desc</Description>
 <Properties>
     <Property name="keymanagement.oauth20.access.token.purge">true</Property>
     <Property name="keymanagement.oauth20.access.token.purge.after.seconds">120</Property>
 </Properties>
</Organization>

重启消息处理器。例如：
```
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
```
此 API 将名为的组织的令牌完全清除属性设为 true。 AutomationOrganization。在这种情况下，访问令牌将从数据库 120 中清除。

另请参阅 <ExpiresIn>元素。

不符合 RFC 标准的行为

OAuthV2 政策返回包含某些不符合 RFC 规范属性的令牌响应。下表显示了 OAuthV2 政策返回的相应不合规属性以及相应的合规属性。

OAuthV2 返回：	符合 RFC 规范的属性为：
`"token_type":"BearerToken"`	`"token_type":"Bearer"`
`"expires_in":"3600"`	`"expires_in":3600` （合规的值是一个数字，而不是字符串。）

此外，当 grant_type = refresh_token 如下时，过期的刷新令牌响应错误：

{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}

然而，符合 RFC 规范的响应为：

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

OAuthV2 政策

内容

示例

VerifyAccessToken

VerifyAccessToken

GenerateAccessToken

生成访问令牌

GenerateAuthorizationCode

生成授权代码

RefreshAccessToken

刷新访问令牌

响应流令牌

生成响应流访问令牌

元素参考

<OAuthV2> 属性

<DisplayName> 元素

<AccessToken> 元素

<AccessTokenPrefix> 元素

<AppEndUser> 元素

<Attributes/Attribute>

在响应中显示或隐藏自定义属性

<ClientId> 元素

<Code> 元素

<ExpiresIn> 元素

<ExternalAccessToken> 元素

<ExternalAuthorization> 元素

<ExternalAuthorizationCode> 元素

<ExternalRefreshToken> 元素

<GenerateResponse> 元素

<GenerateErrorResponse> 元素

<GrantType>

<Operation> 元素

<PassWord> 元素

<RedirectUri> 元素

关于重定向 URI

<RefreshToken> 元素

<RefreshTokenExpiresIn> 元素

<ResponseType> 元素

<ReuseRefreshToken> 元素

<Scope> 元素

<State> 元素

<StoreToken> 元素

<SupportedGrantTypes>/<GrantType> 元素

<Tokens>/<Token> 元素

<UserName> 元素

验证访问令牌

指定请求变量位置

流变量

VerifyAccessToken 操作

GenerateAuthorizationCode 操作

GenerateAccessToken 和 RefreshAccessToken 操作

GenerateAccessTokenImplicitGrant

错误参考信息

运行时错误

部署错误

故障变量

错误响应示例

故障规则示例

政策架构

使用默认 OAuth 配置

完全清除访问令牌

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

正在更新完全清除操作 Edge Private Cloud 4.15.07 的设置

不符合 RFC 标准的行为

相关主题