本页面适用于 Apigee 和 Apigee Hybrid。
查看 Apigee Edge 文档。
内容
OAuthV2 是一种多方政策,用于执行 OAuth 2.0 授权类型操作。这是在 Apigee 上配置 OAuth 2.0 端点的主要政策。
此政策是一项可扩展政策,使用此政策可能会影响费用或使用情况,具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响,请参阅政策类型。
如需详细了解 Apigee 上的 OAuth,请参阅 OAuth 首页。它提供了资源、示例、视频等内容的链接。
示例
VerifyAccessToken
此 OAuthV2 政策配置(通过 VerifyAccessToken 操作)会验证提交到 Apigee 的访问令牌是否有效。当此政策操作被触发时,Apigee 会在请求中查找有效的访问令牌。如果访问令牌有效,则允许该请求继续。如果无效,所有处理都将停止,并在响应中返回错误。
<OAuthV2 name="OAuthV2-Verify-Access-Token"> <Operation>VerifyAccessToken</Operation> </OAuthV2>
客户端应用需要在包含令牌的请求中发送。例如,使用 curl,可能会如下所示:
$ curl https://API_ENDPOINT /weather/forecastrss?w=12797282 \ -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"
其中,API_ENDPOINT 是用于访问 API 的网域,如 Apigee 系统中所配置。
默认情况下,OAuthV2 政策会从 Authorization
标头中提取访问令牌,以去除 Bearer
前缀。您可以使用 AccessToken
配置元素更改此默认行为。
生成访问令牌
如需查看针对每种支持的授权类型请求访问令牌的示例,请参阅获取 OAuth 2.0 令牌。本主题包括以下操作的示例:
刷新访问令牌
如需了解如何使用刷新令牌请求访问令牌,请参阅刷新访问令牌。
JWT 访问令牌
有关如何生成、验证和刷新 JWT 访问令牌的示例,请参阅使用 JWT 访问令牌。
生成响应流访问令牌
有时,您可能需要在响应流中生成访问令牌。例如,您可以这样做,以回应后端服务中的一些自定义验证。在此示例中,用例需要访问令牌和刷新令牌,而非隐式授权类型。在这种情况下,我们将使用密码授权类型来生成令牌。如您所见,实现此操作的技巧是传入带有 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 clientId = context.getVariable("local_clientid"); var clientSecret = context.getVariable("local_secret"); context.setVariable("request.header.Authorization","Basic "+ CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1 .parse(clientId + ':' + clientSecret)));
另请参阅对基本身份验证凭据进行编码。
元素参考
政策参考介绍了 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">
The following table describes attributes that are common to all policy parent elements:
Attribute | Description | Default | Presence |
---|---|---|---|
name |
The internal name of the policy. The value of the Optionally, use the |
N/A | Required |
continueOnError |
Set to Set to |
false | Optional |
enabled |
Set to Set to |
true | Optional |
async |
This attribute is deprecated. |
false | Deprecated |
<DisplayName> element
Use in addition to the name
attribute to label the policy in the
management UI proxy editor with a different, natural-language name.
<DisplayName>Policy Display Name</DisplayName>
Default |
N/A If you omit this element, the value of the policy's |
---|---|
Presence | Optional |
Type | String |
<AccessToken> 元素
<AccessToken>request.header.access_token</AccessToken>
默认情况下,当 Operation
为 VerifyAccessToken
时,政策会要求访问令牌以不记名令牌的形式在 Authorization
标头中发送;也就是说,前缀为“Bearer”,后跟一个空格。您可以使用此元素更改默认值,指定包含要验证的访问令牌的变量名称。使用此元素时,默认情况下,政策不会在变量的内容中查找前缀。如果要指定政策应查找前缀,请也使用 AccessTokenPrefix
元素。
示例:
如果政策配置如下:
<OAuthV2 name="OAuthV2-Verify-Access-Token-in-Header"> <Operation>VerifyAccessToken</Operation> <AccessToken>request.header.access_token</AccessToken> </OAuthV2>
如需使用 curl 传递令牌,您可以使用以下命令:
curl https://
API_ENDPOINT /oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"如果政策配置如下:
<OAuthV2 name="OAuthV2-Verify-Access-Token-in-QueryParam"> <Operation>VerifyAccessToken</Operation> <AccessToken>request.queryparam.token</AccessToken> </OAuthV2>
如需使用 curl 传递令牌,您可以使用以下命令:
curl "https://
API_ENDPOINT /oauth2/validate?token=Rft3dqrs56Blirls56a"
其中,API_ENDPOINT 是用于访问 API 的网域,如 Apigee 系统中所配置。
默认 |
不适用 |
状态 |
可选 |
类型 | 字符串 |
有效值 |
任何变量名称 |
与操作配合使用 |
|
<AccessTokenPrefix> 元素
<AccessTokenPrefix>Prefix</AccessTokenPrefix>
默认情况下,当 Operation
为 VerifyAccessToken
时,政策会要求访问令牌以不记名令牌的形式在 Authorization
标头中发送;也就是说,前缀为“Bearer”,后跟一个空格。如果您使用 AccessToken
元素为传入的访问令牌指定其他位置,则还可以使用此元素 AccessTokenPrefix
来指定其他非标准前缀。
例如,如果您指定以下条件:
<OAuthV2 name="OAuthV2-Verify-Access-Token-Alternative-Header"> <Operation>VerifyAccessToken</Operation> <AccessToken>request.header.token</AccessToken> <AccessTokenPrefix>KEY</AccessTokenPrefix> </OAuthV2>
然后,政策将从 token
请求标头中提取入站访问令牌,方式为:如果标头以“KEY”开头,后跟空格,则政策将删除该前缀和空格,并将剩余值解释为访问令牌。如果标头中不存在指定的前缀,则政策将抛出一个错误。
如果您指定 AccessToken
元素,但未指定 AccessTokenPrefix
元素,则政策会将 AccessToken
元素中指定的变量的整个值解释为访问令牌。
只要在还使用了 AccessToken
元素时,此元素才有效。
默认 |
-无- |
状态 |
可选 |
类型 | 字符串 |
有效值 |
任何字符串 |
与操作配合使用 |
|
<Algorithm>
<Algorithm>algorithm-here</Algorithm>
指定用于为 JWT 访问令牌签名的加密算法。RSA (RS*) 算法使用公钥/密钥对,而 HMAC (HS*) 算法使用共享密钥。此元素对于 GenerateJWTAccessToken
、VerifyJWTAccessToken
和 RefreshJWTAccessToken
操作是必需的。
默认 | 不适用 |
状态 | 使用 GenerateJWTAccessToken 、VerifyJWTAccessToken 和 RefreshJWTAccessToken 操作时是必需的。 |
类型 | 字符串 |
有效值 | HS256、HS384、HS512、RS256、RS384、RS512 |
<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 访问令牌。
默认 |
不适用 |
状态 |
可选 |
类型 | 字符串 |
有效值 |
运行时可访问政策的任何流变量。 |
与授权类型配合使用 |
|
<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 政策手动提取您不想在响应中看到的任何自定义属性。
另请参阅自定义令牌和授权代码。
默认 |
|
状态 |
可选 |
有效值 |
|
与授权类型配合使用 |
|
<CacheExpiryInSeconds> 元素
<CacheExpiryInSeconds ref="propertyset.settings.token-ttl">60</CacheExpiryInSeconds>
此元素只能用于 VerifyAccessToken
操作。它用于指定特定政策执行的访问令牌缓存的存活时间 (TTL)。Apigee 首次验证 OAuth 2 访问令牌时,必须从永久存储区检索访问令牌。这是一个相对耗时的操作,因此 Apigee 会缓存令牌查找的结果,包括令牌状态、令牌对其有效的产品列表,以及附加到令牌的任何自定义属性。在 TTL 过期之前,对 OAuthV2/VerifyAccessToken
的后续调用将读取内存中缓存的结果,这意味着令牌验证速度将会快得多。
访问令牌缓存的默认 TTL 为 180 秒。借助此元素,您可以缩短该 TTL,从而以性能换取正确性。在某些情况下,这样做很有用,例如,如果您有时会撤消令牌,并且希望缩短 Apigee 继续将已撤消的令牌视为有效的时间范围。
支持的范围介于 1 到 180 秒之间。您可以提供流变量和默认值。如果您提供的流变量包含数字值,则该值优先于指定的默认值。
默认 |
不适用
如果您省略此元素,则缓存访问令牌的默认有效期为 180 秒。 |
状态 |
可选 |
类型 |
整数 |
有效值 |
任何非零正整数。指定到期时间(以秒为单位)。 |
与操作配合使用 |
|
属性
下表说明 <CacheExpiryInSeconds>
元素的属性
属性 | 说明 | 默认 | 状态 |
---|---|---|---|
ref |
对包含缓存到期时间值(以秒为单位)的流变量的引用。 如果提供,则流变量值优先于指定的默认值。 |
不适用 | 可选 |
<ClientId> 元素
<ClientId>request.formparam.client_id</ClientId>
在很多情况下,客户端应用必须将客户端 ID 发送到授权服务器。该元素指定 Apigee 应在流变量 request.formparam.client_id
中查找客户端 ID。不支持将 ClientId
设置为任何其他变量。另请参阅获取 OAuth 2.0 令牌。
默认 |
request.formparam.client_id(x www-www-form-urlencoded 并在请求正文中指定) |
状态 |
可选 |
类型 | 字符串 |
有效值 | 流变量:request.formparam.client_id |
与授权类型配合使用 |
也可与 GenerateAuthorizationCode 操作配合使用。 |
<Code> 元素
<Code>request.queryparam.code</Code>
在授权类型流程中,客户端必须将授权代码提交到授权服务器 (Apigee)。通过此元素,您可以指定 Apigee 应在何处查找授权代码。例如,它可以作为查询参数、HTTP 标头或表单参数(默认)发送。
变量 request.queryparam.auth_code
表示授权代码应显示为查询参数,例如 ?auth_code=AfGlvs9
。例如,如需 HTTP 标头中的授权代码,可将此值设为 request.header.auth_code
。另请参阅获取 OAuth 2.0 令牌。
默认 |
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 系统完全清除。另请参阅完全清除访问令牌
默认 |
如果未指定,则系统会应用在系统级别配置的默认值。 |
状态 |
可选 |
类型 | 整数 |
有效值 |
|
与授权类型配合使用 |
也可与 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 令牌。
默认 |
false |
状态 |
可选 |
类型 | 布尔值 |
有效值 | true 或 false |
与授权类型配合使用 |
|
<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
或省略 enabled
特性,则政策将生成并返回响应。例如,对于 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
或省略 <GenerateResponse>
元素,则不会发送任何响应。相反,一组流变量使用与政策的函数相关的值填充。例如,名为 oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code
的流变量将使用新创建的授权代码进行填充。请注意,expires_in 在响应中以秒为单位表示。
默认 |
true |
状态 |
可选 |
类型 | 字符串 |
有效值 | true 或 false |
与授权类型配合使用 |
|
<GenerateErrorResponse> 元素
<GenerateErrorResponse enabled='true'/>
如果设为 true
,则如果 ContinueOnError 属性设置为 true,则政策将生成响应并返回响应。如果为 false
(默认值),则不会发送响应。相反,一组流变量使用与政策的函数相关的值填充。
默认 |
false |
状态 |
可选 |
类型 | 字符串 |
有效值 | true 或 false |
与授权类型配合使用 |
|
<GrantType>
<GrantType>request.queryparam.grant_type</GrantType>
告知政策在何处找到在请求中传递的授权类型参数。根据 OAuth 2.0 规范,必须向请求类型提供访问令牌和授权代码请求。变量可以是标头、查询参数或表单参数(默认)。
例如,request.queryparam.grant_type
表示密码应以查询参数的形式显示,例如 ?grant_type=password
。例如,要在 HTTP 标头中请求授权类型,请将此值设置为 request.header.grant_type
。另请参阅获取 OAuth 2.0 令牌。
默认 |
request.formparam.grant_type(x-www-form-urlencoded,并在请求正文中指定) |
状态 |
可选 |
类型 | 字符串 |
有效值 | 如上所述的变量。 |
与授权类型配合使用 |
|
<Operation> 元素
<Operation>GenerateAuthorizationCode</Operation>
OAuth 2.0 操作由此政策执行。
默认 |
如果未指定 |
状态 |
可选 |
类型 | 字符串 |
有效值 |
其他 JWT 访问令牌操作 如果您更愿意使用 JWT 访问令牌而不是不透明的字符串令牌,则以下操作也可用于生成和验证 JWT 令牌。如需了解详情,请参阅使用 JWT OAuth 令牌操作:
|
<PassWord> 元素
<PassWord>request.queryparam.password</PassWord>
此元素仅用于 密码授权类型。对于密码授权类型,必须向 OAuthV2 政策提供用户凭据(密码和用户名)。<PassWord>
和 <UserName>
元素用于指定 Apigee 找到这些值的变量。如果未指定这些元素,则政策将可在名为 username
和 password
的表单参数中查找值(默认)。如果未找到这些值,则政策会提示错误。您可以使用 <PassWord>
和 <UserName>
元素来参考包含凭据的任何流变量。
例如,您可以使用查询参数在令牌请求中传递密码,并设置如下所示的元素:<PassWord>request.queryparam.password</PassWord>
.
如需在 HTTP 标头中设置密码,请将此值设置为 request.header.password
。
OAuthV2 政策不对这些凭据值执行任何其他操作;Apigee 只是验证它们是否显示。在令牌生成政策执行之前,由 API 开发者负责检索值请求并将其发送到身份提供商。
另请参阅获取 OAuth 2.0 令牌。
默认 |
request.formparam.password(x-www-form-urlencoded,并在请求正文中指定) |
状态 |
可选 |
类型 | 字符串 |
有效值 | 运行时任何政策可用的流变量。 |
与授权类型配合使用 | 密码 |
<PrivateKey>/<Value>
<PrivateKey> <Value ref="variable-name-here"/> </PrivateKey>
提供使用 RSA 算法验证或签署 JWT 格式访问令牌的私钥。 使用 ref
属性在流变量中传递密钥。仅在 Algorithm
元素值为 RS256、RS384 或 RS512 中的一个时使用。如需了解详情,请参阅使用 JWT OAuth 令牌操作。
默认 | 不适用 |
状态 | 当 Algorithm 元素值为 HS256、HS384 或 HS512 中的一个时是必需的。 |
类型 | 字符串 |
有效值 | 包含 PEM 编码 RSA 私钥值的字符串的流变量。 |
<PublicKey>/<Value>
<PublicKey> <Value ref="variable-name-here"/> </PublicKey>
指定用于验证使用 RSA 算法签署的 JWT 格式访问令牌上的签名的公钥或公共证书。使用 ref
属性在流变量中传递密钥/证书。仅在 Algorithm
元素值为 RS256、RS384 或 RS512 中的一个时使用。
默认 | 不适用 |
状态 | 要验证使用 RSA 算法签署的 JWT,您必须使用证书、JWKS 或值元素。 |
类型 | 字符串 |
有效值 | 流变量或字符串。 |
<RedirectUri> 元素
<RedirectUri>request.queryparam.redirect_uri</RedirectUri>
指定 Apigee 应在请求中何处查找 redirect_uri
参数。
关于重定向 URI
重定向 URI 与授权代码和隐式授权类型配合使用。重定向 URI 告知授权服务器 (Apigee) 将授权代码发送到何处(适用于授权代码授权类型)或访问令牌(适用于隐式授权类型)。请务必了解何时需要此参数,何时可选以及此参数的使用方式:
-
(必需)如果使用与请求的客户端密钥关联的开发者应用注册回调网址,且请求中显示
redirect_uri
,则这两个网址必须完全匹配。如果它们不匹配,则返回错误。如需了解如何在 Apigee 上注册开发者应用并指定回调网址,请参阅注册应用并管理 API 密钥。 - (可选)如果已注册回调网址,并且请求中缺少
redirect_uri
,则 Apigee 会重定向到已注册的回调网址。 - (必需)如果未注册回调网址,则需要
redirect_uri
。请注意,在这种情况下,Apigee 将接受任何网址。此案例可能会出现安全问题,因此应仅用于受信任的客户端应用。如果客户端应用不受信任,最佳做法是始终注册回调网址。
您可以在查询参数或标头中发送此参数。变量 request.queryparam.redirect_uri
表示 RedirectUri 应作为查询参数显示,例如 ?redirect_uri=login.myapp.com
。例如,要在 HTTP 标头中提供 RedirectUri,请将此值设置为 request.header.redirect_uri
。另请参阅获取 OAuth 2.0 令牌。
默认 |
request.formparam.redirect_uri(x-www-form-urlencoded 并在请求正文中指定) |
状态 |
可选 |
类型 | 字符串 |
有效值 | 运行时可访问政策的任何流变量 |
与授权类型配合使用 |
与 GenerateAuthorizationCode 操作配合使用。 |
<RefreshToken> 元素
<RefreshToken>request.queryparam.refreshtoken</RefreshToken>
使用刷新令牌请求访问令牌时,必须在请求中提供刷新令牌。此元素可让您指定 Apigee 应在何处查找刷新令牌。例如,它可以作为查询参数、HTTP 标头或表单参数(默认)发送。
变量 request.queryparam.refreshtoken
表示刷新令牌应作为查询参数显示,例如 ?refresh_token=login.myapp.com
。例如,要在 HTTP 标头中提供 RefreshToken,请将此值设置为 request.header.refresh_token
。另请参阅获取 OAuth 2.0 令牌。
默认 |
request.formparam.refresh_token(x www-www-form-urlencoded 并在请求正文中指定) |
状态 |
可选 |
类型 | 字符串 |
有效值 | 运行时可访问政策的任何流变量 |
与授权类型配合使用 |
|
<RefreshTokenExpiresIn> 元素
<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>
强制以毫秒为单位执行刷新令牌的过期时间。过期时间值是系统生成的值加上 <RefreshTokenExpiresIn>
值。如果 <RefreshTokenExpiresIn>
设置为 -1,则刷新令牌会根据 OAuth 刷新令牌的有效期到期。如果未指定 <RefreshTokenExpiresIn>
,则系统会应用默认值。
您也可以在运行时使用硬编码的默认值或参考流变量来设置过期时间。例如,您可以在键值对映射中存储令牌过期时间值,检索它,将其分配给变量,然后在政策中参考。例如:kvm.oauth.expires_in
。
以下节指定了一个流变量和一个默认值。请注意,流变量值优先于指定的默认值。
<RefreshTokenExpiresIn ref="kvm.oauth.expires_in"> 86400000 <!--value in milliseconds--> </RefreshTokenExpiresIn>
默认 |
2592000000 毫秒(30 天)(自 2023 年 5 月 31 日起生效) |
状态 |
可选 |
类型 | 整数 |
有效值 |
|
与授权类型配合使用 |
|
<ResponseType> 元素
<ResponseType>request.queryparam.response_type</ResponseType>
此元素用于告知 Apigee 客户端应用请求的授权类型。它仅与授权代码和隐式授权类型流程配合使用。
默认情况下,Apigee 会在 response_type
查询参数中查找响应类型值。如果要替换此默认行为,请使用 <ResponseType> 元素来配置包含响应类型值的流变量。例如,如果您将此元素设置为 request.header.response_type
,则 Apigee 会查找在请求标头中传递的响应类型。另请参阅获取 OAuth 2.0 令牌。
默认 |
request.formparam.response_type(x-www-form-urlencoded,并在请求正文中指定) |
状态 |
可选。如果您希望替换默认行为,请使用此元素。 |
类型 | 字符串 |
有效值 | code (适用于授权代码授权类型)或 token (适用于隐式授权类型) |
与授权类型配合使用 |
|
<ReuseRefreshToken> 元素
<ReuseRefreshToken>true</ReuseRefreshToken>
当设置为 true
时,现有的刷新令牌会被重复使用,直到其过期为止。如果为 false
,则在提供有效的刷新令牌时,Apigee 会发出新的刷新令牌。
默认 |
|
状态 |
可选 |
类型 | 布尔值 |
有效值 |
|
与授权类型配合使用 |
|
<RFCCompliantRequestResponse> 元素
<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>
如果为 true
,则政策符合 RFC6749 标准,并且启用以下合规行为:
- 错误和非错误响应将包含 HTTP
Cache-Control
响应标头字段,以符合 RFC2616(超文本传输协议 -- HTTP/1.1),值为no-store
(在包含令牌、凭据或其他敏感信息的任何响应中)以及值为no-cache
的Pragma
响应标头字段。 expires_in
属性将以字母数字格式表示。为了保持一致性,refresh_token_expires_in
也是字母数字。- 用于生成令牌的 OAuthV2 响应将包含符合 RFC 标准的
Bearer
标头字段,而不是BearerToken
。 - 响应载荷中的错误消息会采用以下格式:
{"error" : "xxx", "error_description" :"yyy"}
用于刷新令牌错误。
默认 |
|
状态 |
可选 |
类型 | 布尔值 |
有效值 | true 或 false |
与授权类型配合使用 | 全部 |
<SecretKey>/<Value>
<SecretKey> <Value ref="your-variable-name"/> </SecretKey>
提供用于通过 HMAC 算法验证或签署的 JWT 格式访问令牌的密钥。仅在算法是 HS256、HS384、HS512 之一时使用。使用 ref
属性在流变量中传递密钥。如需了解详情,请参阅使用 JWT OAuth 令牌操作。
Apigee 为 HS256/HS384/HS512 算法强制执行最小密钥强度。HS256 的最小密钥长度为 32 个字节,HS384 为 48 个字节,而 HS512 则为 64 个字节。使用较低强度的密钥会导致运行时错误。
默认 | 不适用 |
状态 | HMAC 算法所需的属性。 |
类型 | 字符串 |
有效值 | 流变量 |
<Scope> 元素
<Scope>request.queryparam.scope</Scope>
如果此元素存在于 GenerateAccessToken 或 GenerateAuthorizationCode 政策中,则用于指定授权令牌或代码的范围。这些值通常会传递给客户端应用中的政策。您可配置元素以采用流变量,同时可以选择范围在请求中的传递方式。在以下示例中,request.queryparam.scope
表示应显示为查询参数的范围,例如 ?scope=READ
。例如,如需在 HTTP 标头中使用范围,请将此值设置为 request.header.scope
。
如果该元素显示在“VerifyAccessToken”政策中,则用于指定此政策应该强制执行的范围。在此类政策中,该值必须为“硬编码”范围名称,但不能使用变量。例如:
<Scope>A B</Scope>
另请参阅使用 OAuth2 范围和获取 OAuth 2.0 令牌。
默认 |
无范围 |
状态 |
可选 |
类型 | 字符串 |
有效值 |
与生成*政策配合使用时,则为流变量。 与 VerifyAccessToken 配合使用时,空格分隔的范围名称列表(字符串)。 |
与授权类型配合使用 |
|
<State> 元素
<State>request.queryparam.state</State>
如果客户端应用必须将状态信息发送给授权服务器,则此元素允许您指定 Apigee 应在何处查找状态值。例如,它可以作为查询参数或 HTTP 标头发送。状态值通常作为一种安全措施,用于防止 CSRF 攻击。
例如,request.queryparam.state
表示状态应该显示为查询参数,例如 ?state=HjoiuKJH32
。例如,如需在 HTTP 标头中提供状态,请将此值设置为 request.header.state
。另请参阅获取 OAuth 2.0 令牌。
默认 |
无状态 |
状态 |
可选 |
类型 | 字符串 |
有效值 | 运行时可访问政策的任何流变量 |
与授权类型配合使用 |
|
<StoreToken> 元素
<StoreToken>true</StoreToken>
当 <ExternalAuthorization>
元素为 true
时,请将此元素设置为 true
。<StoreToken>
元素告知 Apigee 存储外部访问令牌。否则将不会保留。
默认 |
false |
状态 |
可选 |
类型 | 布尔值 |
有效值 | true 或 false |
与授权类型配合使用 |
|
<SupportedGrantTypes>/<GrantType> 元素
<SupportedGrantTypes> <GrantType>authorization_code</GrantType> <GrantType>client_credentials</GrantType> <GrantType>implicit</GrantType> <GrantType>password</GrantType> </SupportedGrantTypes>
指定 Apigee 上 OAuth 令牌端点支持的授权类型。一个端点可支持多个授权类型(也就是说,可以配置端点为多个授权类型分配访问令牌)。如需详细了解端点,请参阅了解 OAuth 端点。授权类型在令牌请求中以 grant_type
参数的形式传递。
如果未指定受支持的授权类型,则仅允许的授权类型是 authorization_code
和 implicit
。另请参阅 <GrantType> 元素(这是一个高级别元素,用于指定 Apigee 应在何处查找在客户端请求中传递的 grant_type
参数)。Apigee 将确保 grant_type
参数的值与某个受支持的授权类型匹配。
默认 |
authorization _code 和隐式 |
状态 |
必填 |
类型 | 字符串 |
有效值 |
|
<Tokens>/<Token> 元素
与 ValidateToken 和 InvalidateToken 操作配合使用。另请参阅批准和撤消访问令牌。<Token> 元素可识别定义要撤销的令牌来源的流变量。例如,如果开发者想要将访问令牌作为名为 access_token
的查询参数提交,请使用 request.queryparam.access_token
。
<UserName> 元素
<UserName>request.queryparam.user_name</UserName>
此元素仅用于 密码授权类型。对于密码授权类型,必须向 OAuthV2 政策提供用户凭据(密码和用户名)。<PassWord>
和 <UserName>
元素用于指定 Apigee 找到这些值的变量。如果未指定这些元素,则政策将可在名为 username
和 password
的表单参数中查找值(默认)。如果未找到这些值,则政策会提示错误。您可以使用 <PassWord>
和 <UserName>
元素来参考包含凭据的任何流变量。
例如,您可以在查询参数中传递用户名,并如下设置 <UserName>
元素:<UserName>request.queryparam.username</UserName>
.
如果要求在 HTTP 标头中提供用户名,请设置此值设为 request.header.username
。
OAuthV2 政策不对这些凭据值执行任何其他操作;Apigee 只是验证它们是否显示。在令牌生成政策执行之前,由 API 开发者负责检索值请求并将其发送到身份提供商。
另请参阅获取 OAuth 2.0 令牌。
默认 |
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 规范。如果您的应用需要违反 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 |
与已注册客户端应用关联的开发者或 AppGroup 的 ID。 |
developer.app.name |
与已注册客户端应用关联的开发者或 AppGroup 应用的名称。 |
client_id |
已注册客户端应用的客户端 ID。 |
grant_type |
与请求关联的授权类型。 不支持 VerifyJWTAccessToken 操作。 |
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)表示访问令牌被撤消的原因。 不支持 值可以是 |
应用专用变量
这些变量与与令牌关联的开发者应用相关。
变量 | 说明 |
---|---|
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} |
已注册客户端应用的已命名自定义属性。 |
AppGroup 专用变量
以下流变量包含有关令牌的 AppGroup 的信息,并由政策填充。仅当 verifyapikey.{policy_name}.app.appType
为“AppGroup”时,才会填充这些 AppGroup 属性。
变量 | 说明 |
---|---|
appgroup.displayName |
AppGroup 显示名称。 |
appgroup.name |
AppGroup 的名称。 |
appgroup.id |
AppGroup ID。 |
appOwnerStatus |
应用所有者的状态:“active”“inactive”或“login_lock”。 |
created_at |
AppGroup 的创建日期/时间戳。 |
created_by |
创建 AppGroup 的开发者的电子邮件地址。 |
last_modified_at |
上次修改 AppGroup 的日期/时间戳。 |
last_modified_by |
上次修改 AppGroup 的开发者的电子邮件地址。 |
{appgroup_custom_attributes} |
任何自定义 AppGroup 属性。指定自定义属性的名称。 |
开发者专用变量
如果 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} |
开发者的已命名自定义属性。 |
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> 元素。 |
错误参考信息
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.
Fault code | HTTP status | Cause | Thrown by operations |
---|---|---|---|
steps.oauth.v2.access_token_expired |
401 |
The access token is expired. |
|
steps.oauth.v2.access_token_not_approved |
401 |
The access token was revoked. | VerifyAccessToken |
steps.oauth.v2.apiproduct_doesnot_exist |
401 |
The requested API product does not exist in any of the API products associated with the access token. | VerifyAccessToken |
steps.oauth.v2.FailedToResolveAccessToken |
500 |
The policy expected to find an access token in a variable specified in the
<AccessToken> element, but the variable could not be resolved. |
GenerateAccessToken |
steps.oauth.v2.FailedToResolveAuthorizationCode |
500 |
The policy expected to find an authorization code in a variable specified in the
<Code> element, but the variable could not be resolved. |
GenerateAuthorizationCode |
steps.oauth.v2.FailedToResolveClientId |
500 |
The policy expected to find the Client ID in a variable specified in the
<ClientId> element, but the variable could not be resolved. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
steps.oauth.v2.FailedToResolveRefreshToken |
500 |
The policy expected to find a refresh token in a variable specified in the
<RefreshToken> element, but the variable could not be resolved. |
RefreshAccessToken |
steps.oauth.v2.FailedToResolveToken |
500 |
The policy expected to find a token in a variable specified in the
<Tokens> element, but the variable could not be resolved. |
|
steps.oauth.v2.InsufficientScope |
403 | The access token presented in the request has a scope that does not match the scope specified in the verify access token policy. To learn about scope, see Working with OAuth2 scopes. | VerifyAccessToken |
steps.oauth.v2.invalid_client |
401 |
This error name is returned when the |
GenerateAccessToken RefreshAccessToken |
steps.oauth.v2.InvalidRequest |
400 | This error name is used for multiple different kinds of errors, typically for missing
or incorrect parameters sent in the request. If <GenerateResponse> is
set to false , use fault variables (described below) to retrieve details about
the error, such as the fault name and cause. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
steps.oauth.v2.InvalidAccessToken |
401 |
The authorization header does not have the word Bearer , which is required. For
example: Authorization: Bearer your_access_token |
VerifyAccessToken |
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound |
401 |
The currently executing API proxy or operation is not in the Product associated with the access token. Tips: Be sure that the product associated with the access token is configured correctly. For example, if you use wildcards in resource paths, be sure the wildcards are being used correctly. See Managing API products for details. See also Oauth2.0 Access Token Verification throws "Invalid API call as no apiproduct match found" error for more guidance on causes for this error. |
VerifyAccessToken |
steps.oauth.v2.InvalidClientIdentifier |
500 |
This error name is returned when the |
|
steps.oauth.v2.InvalidParameter |
500 |
The policy must specify either an access token or an authorization code, but not both. | GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.InvalidTokenType |
500 |
The <Tokens>/<Token> element requires you to specify the token
type (for example, refreshtoken ). If the client passes the wrong type, this
error is thrown. |
ValidateToken InvalidateToken |
steps.oauth.v2.MissingParameter |
500 |
The response type is token , but no grant types are specified. |
GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.UnSupportedGrantType |
500 |
The client specified a grant type that is unsupported by the policy (not listed in the
|
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
JWT token-specific runtime errors
Runtime error codes and descriptions for JWT auth token flows depend on the OAuth2 flow context:
- If the flow context is token generation or refresh, see Error codes for JWT token generation and refresh flows below.
- For the token verification flow, see Error codes for token verification flows below.
Error codes for JWT token generation and refresh flows
For OAuth2 flows that generate or refresh JWT tokens, error responses adhere to the error responses specified in RFC6749. For details, see Section 5.2 Error Response.
Error codes for the token verification flow
The error codes listed in the following table apply to VerifyAccessToken operation only.
Fault code | HTTP status | Cause | Thrown by operations |
---|---|---|---|
oauth.v2.JWTSigningFailed |
401 |
The policy was unable to sign the JWT. |
|
oauth.v2.InvalidValueForJWTAlgorithm |
401 |
This occurs when the algorithm is not present in the JWT access token or when the value is not supported. |
|
oauth.v2.InsufficientKeyLength |
401 |
In Generation of JWT, for a key less than the minimum size for the HS384 or HS512 algorithms |
|
oauth.v2.JWTAlgorithmMismatch |
401 |
The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match. |
|
oauth.v2.JWTDecodingFailed |
401 |
The policy was unable to decode the JWT. The JWT is possibly corrupted. |
|
oauth.v2.MissingMandatoryClaimsInJWT |
401 |
Occurs when the required claims are not present in the Jwt Access token |
|
oauth.v2.InvalidJWTSignature |
401 |
This occurs when the signature of JWT access token could not be verified or when the signature is invalid. |
|
oauth.v2.InvalidTypeInJWTHeader |
401 |
Occurs when the JWT's type is not at+Jwt |
|
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Error name | Cause |
---|---|
InvalidValueForExpiresIn |
For the |
InvalidValueForRefreshTokenExpiresIn |
For the <RefreshTokenExpiresIn> element, valid values are positive
integers and -1 . |
InvalidGrantType |
An invalid grant type is specified in the <SupportedGrantTypes>
element. See the policy reference for a list of valid types. |
ExpiresInNotApplicableForOperation |
Be sure that the operations specified in the <Operations> element support
expiration. For example, the VerifyToken operation does not. |
RefreshTokenExpiresInNotApplicableForOperation |
Be sure that the operations specified in the <Operations> element support refresh
token expiration. For example, the VerifyToken operation does not. |
GrantTypesNotApplicableForOperation |
Be sure that the grant types specified in <SupportedGrantTypes> are supported for
the specified operation. |
OperationRequired |
You must specify an operation in this policy using the |
InvalidOperation |
You must specify a valid operation in this policy using the
|
TokenValueRequired |
You must specify a token <Token> value in the
<Tokens> element. |
JWT token-specific deployment errors
These deployment errors are specific to policies that use JWT token operations.
Error name | Cause |
---|---|
InvalidValueForAlgorithm |
The algorithm specified in the <Algorithm> element is not
among the list of available algorithms or is not present. |
MissingKeyConfiguration |
The required <SecretKey> , <PrivateKey> , or
<PublicKey> elements are missing, depending on which algorithm is used. |
EmptyValueElementForKeyConfiguration |
The required child element <Value> is not defined in the
<PrivateKey> , <PublicKey> , or <SecretKey> elements |
InvalidKeyConfiguration |
The <PrivateKey> element is not used with RSA family algorithms or the <SecretKey>
element is not used with HS Family algorithms. |
EmptyRefAttributeForKeyconfiguration |
The ref attribute of the child element <Value> of
the <PrivateKey> , <PublicKey> or <SecretKey> elements is empty. |
InvalidVariableNameForKey |
The flow variable name specified in the ref attribute of the child
element <Value> of the <PrivateKey> ,
<PublicKey> or <SecretKey> elements does not
contain the private prefix. |
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 = "InvalidRequest" |
oauthV2.policy_name.failed |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.GenerateAccesstoken.failed = true |
oauthV2.policy_name.fault.name |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.GenerateAccesstoken.fault.name = InvalidRequest
|
oauthV2.policy_name.fault.cause |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.GenerateAccesstoken.cause = Required param : grant_type |
Example error response
These responses are sent back to the client if the <GenerateResponse>
element is true.
If <GenerateResponse>
is true, the policy returns errors
in this format for operations that generate tokens and codes. For a complete list, see see
OAuth HTTP error
response reference.
{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}
If <GenerateResponse>
is true, the policy returns errors
in this format for verify and validate operations. For a complete list, see see OAuth HTTP error
response reference.
{ { "fault":{ "faultstring":"Invalid Access Token", "detail":{ "errorcode":"keymanagement.service.invalid_access_token" } } }
Example fault rule
<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>
对 Storage 中的令牌进行哈希处理
如果您使用的是 Apigee Hybrid 或 Apigee,则默认情况下,OAuthV2 访问令牌和刷新令牌会在存储在运行时 Cassandra 数据库中时进行哈希处理。哈希处理可防止数据库被入侵时使用令牌。
使用默认 OAuth 配置
Apigee 上的每个组织(甚至是免费适用组织)均使用 OAuth 令牌端点进行配置。端点在名为 OAuth 的 API 代理中预配置了政策。在 Apigee 上创建账号后,您可以立即开始使用令牌端点。如需了解详情,请参阅了解 OAuth 端点。
完全清除访问令牌
默认情况下,OAuth2 令牌将在访问令牌和刷新令牌(如果存在)过期 3 天(259200 秒)后,从 Apigee 系统中完全清除。
不符合 RFC 标准的行为
默认情况下,指定了 GenerateAccessToken 操作的 OAuthV2 政策会返回包含某些不符合 RFC 规范的属性的令牌响应。下表显示了 OAuthV2 政策返回的相应不合规属性以及相应的合规属性。
OAuthV2 返回: | 符合 RFC 规范的属性为: |
---|---|
"token_type":"BearerToken" |
"token_type":"Bearer"
|
"expires_in":"3600" |
"expires_in":3600
(合规的值是一个数字,而不是字符串。) |
此外,当 grant_type = refresh_token
如下时,过期的刷新令牌响应错误:
{"ErrorCode" : "InvalidRequest", "Error" :"Refresh Token expired"}
然而,符合 RFC 规范的响应为:
{"error" : "invalid_grant", "error_description" :"refresh token expired"}