注意:此产品的某些方面处于 Beta 版阶段。Hybrid 安装选项是 GA。要加入 Beta 版计划,请与您的 Apigee 代表联系。

OAuthV2 政策

内容

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

提示:如果您想详细了解 Apigee 上的 OAuth,请参阅 OAuth 首页。它提供了资源、示例、视频等内容的链接。

示例

VerifyAccessToken

VerifyAccessToken

此 OAuthV2 政策配置(通过 VerifyAccessToken 操作)会验证提交到 Apigee 的访问令牌是否有效。当此政策操作被触发时,Apigee 会在请求中查找有效的访问令牌。如果访问令牌有效,则允许该请求继续。如果无效,所有处理都将停止,并在响应中返回错误。

<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 https://your_host_alias/weather/forecastrss?w=12797282 \
  -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"

其中 your_host_alias 是用于访问您的 API 的公共域名,如替换文件中的 virtualhosts.hostAliases 属性中所配置。请参阅配置集群

默认情况下,Apigee 在 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,即使在政策失败后,仍可以继续执行流。

可选
enabled

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

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

可选
async

此属性已弃用。

已弃用

<DisplayName> 元素

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

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

不适用

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

状态 可选
类型 字符串

<AccessToken> 元素

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

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

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

curl https://your_host_alias/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

指定了 <AccessToken>request.queryparam.access_token</AccessToken> 的示例:

curl "https://your_host_alias/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

其中 your_host_alias 是用于访问您的 API 的公共域名,如替换文件中的 virtualhosts.hostAliases 属性中所配置。请参阅配置集群

默认:

显示:

可选

类型: 字符串
与操作配合使用
  • VerifyAccessToken

<AccessTokenPrefix> 元素

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

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

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

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

默认:

不记名

显示:

可选

类型: 字符串
有效值:

不记名

与操作配合使用
  • VerifyAccessToken

<AppEndUser> 元素

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

如果必须将应用最终用户 ID 发送到授权服务器,则可以使用此元素指定 Apigee 在何处查找最终用户 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 可实现此目的。不过,如果稍后使用刷新令牌生成新访问令牌,则访问令牌中的原始自定义属性将显示在刷新令牌响应中。这是因为 Apigee 不会记住在生成访问令牌政策中最初将 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 发送到授权服务器。通过此元素,您可以指定 Apigee 应在何处查找客户端 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)。通过此元素,您可以指定 Apigee 应在何处查找授权代码。例如,它可以作为查询参数、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 会将以下实体缓存至少 180 秒。

  • OAuth 访问令牌。这意味着 OAuth v2 政策上的 ExpiresIn 元素无法在 180 秒之内使访问令牌到期。
  • 密钥管理服务 (KMS) 实体(应用、开发者、API 产品)。
  • OAuth 令牌和 KMS 实体的自定义属性。

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

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

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

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

默认:

如果未指定,则系统会应用在系统级别配置的默认值。

显示:

可选

类型: 整数
有效值:
  • 任何非零正整数。指定以毫秒为单位表示的过期时间。虽然此元素的值以毫秒为单位,但令牌的 expires_in 属性和 expires_in 流变量中设置的值以秒为单位。
  • 根据 OAuth 访问令牌的过期期限-1 将到期。

    注意:指定任何其他负整数或零会导致部署错误。
与授权类型配合使用
  • authorization_code
  • 隐式
  • 密码
  • client_credentials
  • refresh_token

也可与 GenerateAuthorizationCode 操作配合使用。

<ExternalAccessToken> 元素

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

告知 Apigee 在何处查找外部访问令牌(非 Apigee 生成的访问令牌)。

变量 request.queryparam.external_access_token 表示外部访问令牌应作为查询参数显示,例如 ?external_access_token=12345678。例如,要在 HTTP 标头中请求外部访问令牌,请将此值设置为 request.header.external_access_token。另请参阅使用第三方 OAuth 令牌

<ExternalAuthorization> 元素

<ExternalAuthorization>true</ExternalAuthorization>

如果此元素为 false 或不存在,则 Apigee 会根据 Apigee 授权存储区正常验证 client_id 和 client_secret。如果您要使用第三方 OAuth 令牌,请使用此元素。要详细了解如何使用此元素,请参阅使用第三方 OAuth 令牌

默认:

显示:

可选

类型: 布尔值
有效值: true 或 false
与授权类型配合使用
  • authorization_code
  • 密码
  • client_credentials

<ExternalAuthorizationCode> 元素

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

告知 Apigee 在何处查找外部授权代码(不是 Apigee 生成的授权代码)。

变量 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 在何处可以找到外部刷新令牌(不是由 Apigee 生成的刷新令牌)。

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

默认:

显示:

可选

类型: 字符串
有效值: true 或 false
与授权类型配合使用
  • 隐式
  • 密码
  • client_credentials
  • refresh_token
  • 也可与 GenerateAuthorizationCode 操作配合使用。

<GenerateErrorResponse> 元素

<GenerateErrorResponse enabled='true'/>

如果设为 true,则如果 ContinueOnError 属性设置为 true,则政策将生成响应并返回响应。如果为 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>,Apigee 会查看 <SupportedGrantTypes> 列表。只有针对这些授权类型的操作才会成功。换句话说,如果您在 <SupportedGrantTypes> 列表中指定了 <GrantType>,则可以省略 <Operation>。如果 <Operation><SupportedGrantTypes> 均未指定,则默认授权类型是 authorization_code。也就是说,授权代码授权类型的请求将成功,但其他所有类型的请求将失败。

显示:

可选

类型: 字符串
有效值:

<PassWord> 元素

<PassWord>request.queryparam.password</PassWord>

此元素仅用于 密码授权类型。对于密码授权类型,必须向 OAuthV2 政策提供用户凭据(密码和用户名)。<PassWord><UserName> 元素用于指定 Apigee 找到这些值的变量。如果未指定这些元素,则政策将可在名为 usernamepassword 的表单参数中查找值(默认)。如果未找到这些值,则政策会提示错误。您可以使用 <PassWord><UserName> 元素来参考包含凭据的任何流变量。

例如,您可以使用查询参数在令牌请求中传递密码,并设置如下所示的元素:<PassWord>request.queryparam.password</PassWord>.如需在 HTTP 标头中设置密码,请将此值设置为 request.header.password

OAuthV2 政策不对这些凭据值执行任何其他操作;Apigee 只是验证它们是否显示。在令牌生成政策执行之前,由 API 开发者负责检索值请求并将其发送到身份提供商。

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

默认:

request.formparam.password(x-www-form-urlencoded,并在请求正文中指定)

显示:

可选

类型: 字符串
有效值: 运行时任何政策可用的流变量。
与授权类型配合使用 密码

<RedirectUri> 元素

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

指定 Apigee 应在请求中何处查找 redirect_uri 参数。

关于重定向 URI

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

  • (必需)如果使用与请求的客户端密钥关联的开发者应用注册回调网址,且请求中显示 request_uri,则这两个网址必须完全匹配。如果它们不匹配,则返回错误。如需了解如何在 Apigee 上注册开发者应用并指定回调网址,请参阅注册应用并管理 API 密钥

  • (可选)如果已注册回调网址,并且请求中缺少 request_uri,则 Apigee 会重定向到已注册的回调网址。
  • (必需)如果未注册回调网址,则需要 request_uri。请注意,在这种情况下,Apigee 将接受任何网址。此案例可能会出现安全问题,因此应仅用于受信任的客户端应用。如果客户端应用不受信任,最佳做法是始终注册回调网址。

您可以在查询参数或标头中发送此参数。变量 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>

使用刷新令牌请求访问令牌时,必须在请求中提供刷新令牌。此元素可让您指定 Apigee 应在何处查找刷新令牌。例如,它可以作为查询参数、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 支持团队联系。

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

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

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

默认:

如果未指定,则系统会应用在系统级别配置的默认值。

显示:

可选

类型: 整数
有效值:
  • 任何非零正整数。指定过期时间以毫秒为单位。
  • 根据 OAuth 刷新令牌的过期期限-1 将到期。

    注意:指定任何其他负整数或零会导致部署错误。
与授权类型配合使用
  • authorization_code
  • 密码
  • refresh_token

<ResponseType> 元素

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

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

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

默认:

request.formparam.response_type(x-www-form-urlencoded,并在请求正文中指定)

显示:

可选。如果您希望替换默认行为,请使用此元素。

类型: 字符串
有效值: code(适用于授权代码授权类型)或 token(适用于隐式授权类型)
与授权类型配合使用
  • 隐式
  • 与 GenerateAuthorizationCode 操作配合使用。

<ReuseRefreshToken> 元素

<ReuseRefreshToken>true</ReuseRefreshToken>

当设置为 true 时,现有的刷新令牌会被重复使用,直到其过期为止。如果为 false,则在提供有效的刷新令牌时,Apigee 会发出新的刷新令牌。

默认:

false

显示:

可选

类型: 布尔值
有效值:

truefalse

与授权类型配合使用
  • 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>

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

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

默认:

无状态

显示:

可选

类型: 字符串
有效值: 运行时可访问政策的任何流变量
与授权类型配合使用
  • 全部
  • 也可与 GenerateAuthorizationCode 操作配合使用

<StoreToken> 元素

 <StoreToken>true</StoreToken>

<ExternalAuthorization> 元素为 true 时,请将此元素设置为 true<StoreToken> 元素告知 Apigee 存储外部访问令牌。否则将不会保留。

默认:

显示:

可选

类型: 布尔值
有效值: 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 上 OAuth 令牌端点支持的授权类型。一个端点可支持多个授权类型(也就是说,可以配置端点为多个授权类型分配访问令牌)。如需详细了解端点,请参阅了解 OAuth 端点。授权类型在令牌请求中以 grant_type 参数的形式传递。

如果未指定受支持的授权类型,则仅允许的授权类型是 authorization_codeimplicit。另请参阅 <GrantType> 元素(这是一个高级别元素,用于指定 Apigee 应在何处查找在客户端请求中传递的 grant_type 参数)。Apigee 将确保 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>

此元素仅用于 密码授权类型。对于密码授权类型,必须向 OAuthV2 政策提供用户凭据(密码和用户名)。<PassWord><UserName> 元素用于指定 Apigee 找到这些值的变量。如果未指定这些元素,则政策将可在名为 usernamepassword 的表单参数中查找值(默认)。如果未找到这些值,则政策会提示错误。您可以使用 <PassWord><UserName> 元素来参考包含凭据的任何流变量。

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

OAuthV2 政策不对这些凭据值执行任何其他操作;Apigee 只是验证它们是否显示。在令牌生成政策执行之前,由 API 开发者负责检索值请求并将其发送到身份提供商。

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

默认:

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 标头(名称并非授权)中显示,请使用此设置。

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

指定请求变量位置

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

令牌专用变量

变量 说明
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_APPREVOKED_BY_ENDUSERREVOKED_BY_APP_ENDUSERTOKEN_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 approvedrevoked
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 approvedrevoked

GenerateAccessTokenImplicitGrant

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

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

示例: oauthv2accesstoken.RefreshTokenPolicy.access_token

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

错误参考信息

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

运行时错误

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

故障代码 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_clientInvalidClientIdentifier 名称。如需了解详情并查看示例,请参阅 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_clientInvalidClientIdentifier 名称。如需了解详情并查看示例,请参阅 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> 值。

故障变量

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

变量 其中 示例
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,则会将这些响应发送回客户端。

如果 <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 上的每个组织(甚至是免费适用组织)均使用 OAuth 令牌端点进行配置。端点在名为 OAuth 的 API 代理中预配置了政策。在 Apigee 上创建帐号后,您可以立即开始使用令牌端点。如需了解详情,请参阅了解 OAuth 端点

完全清除访问令牌

默认情况下,OAuth2 令牌将在访问令牌和刷新令牌(如果存在)过期 3 天(259200 秒)后,从 Apigee 系统中完全清除。在某些情况下,您可能需要更改此默认值。例如,如果生成大量令牌,您可能希望缩短完全清除时间以节省磁盘空间。

不符合 RFC 标准的行为

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