自定义令牌和授权代码

本页面适用于 ApigeeApigee Hybrid

查看 Apigee Edge 文档。

令牌和授权代码元数据简介

Apigee 可生成 OAuth 访问令牌、刷新令牌和授权代码,并将其分发给经过身份验证的应用。在生成时,Apigee 会存储这些令牌和代码。之后,当 Apigee 收到这些令牌或代码的入站 API 请求时,Apigee 会使用存储的信息来授权请求。

Apigee 生成这些 OAuth 工件时,还会将元数据附加到令牌或代码。例如,访问令牌与定义失效时间、关联应用和开发者以及其他信息的名称/值对相关联。

Apigee 访问令牌的 JSON 表示法如下所示:

{
  "issued_at" : "1372170159093",
  "application_name" : "ccd1803b-b557-4520-bd62-ddd3abf8e501",
  "scope" : "READ",
  "status" : "approved",
  "api_product_list" : "[Product1,Product2]",
  "api_product_list_json" : ["Product1", "Product2"],
  "expires_in" : "3599", //--in seconds
  "developer.email" : "joe@weathersample.com",
  "organization_id" : "0",
  "refresh_token" : "82XMXgDyHTpFyXOaApj8C2AGIPnN2IZe",
  "client_id" : "deAVedE0W9Z9U35PAMaAJYphBJCGdrND",
  "access_token" : "shTUmeI1geSKin0TODcGLXBNe9vp",
  "organization_name" : "apifactory",
  "refresh_count" : "0"
}

向 OAuth 令牌和授权代码添加自定义特性

有时,将自定义元数据附加到访问令牌会很有用。例如,您可能希望为令牌添加用户的用户名、组成员资格或角色以及客户 ID、会话标识符或其他任意信息。在 Apigee 中,此类数据称为“自定义特属性”。随后,在 API 请求范围内验证令牌时,该数据将通过上下文变量提供给 API 代理。API 代理可以根据附加到令牌的自定义数据做出精细的授权或路由决策。

如需将任意数据附加到令牌,请在 OAuthV2 政策中使用 <Attributes> 元素。您可以指定自定义特性的名称和值。例如,以下政策配置会生成令牌,并将名为“tenant_list”的自定义特性附加到该令牌:

<OAuthV2 name="GenerateAccessToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>600000</ExpiresIn>
  <GenerateResponse />
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <Attributes> 
    <Attribute name="tenant_list" ref="tenant_list_retrieved_from_external_service" display="false"/>
  </Attributes>
</OAuthV2>

您可以指定多个自定义属性,并且可以在生成时隐式将其附加到授权代码 (<Operation>GenerateAuthorizationCode</Operation>) 或令牌 (<Operation>GenerateAccessToken</Operation>)。

display 设置为 true(默认值)时,系统会在响应中返回自定义属性,在其中这些属性可由应用查看,或者传递给最终用户。将 display 设置为 false 时,自定义属性将存储在数据存储区中,但不会在响应消息中返回。无论哪种情况,令牌通过验证后,都可向 API 代理中的政策提供自定义数据。

如需详细了解 display 选项,请参阅在响应中显示或隐藏自定义特性

在运行时获取自定义访问令牌属性

调用 OAuthV2/VerifyAccessToken 时,Apigee 会在令牌存储区中查找该令牌来验证令牌。然后,Apigee 会填充一组上下文变量,其中包含有关令牌的信息。其中包括:

  • organization_name
  • developer.id
  • developer.app.name
  • client_id
  • grant_type
  • token_type
  • access_token
  • issued_at
  • expires_in //--in seconds
  • status
  • scope
  • apiproduct.name*

如果令牌上有任何自定义属性,则这些自定义属性可通过名为 accesstoken.{custom_attribute} 的上下文变量提供。例如,假设系统从上述政策发出令牌。验证此类令牌后,将有另一个名为 accesstoken.tenant_list 的上下文变量,其中包含生成令牌时存储的值。

然后,政策或条件可以引用这些变量,并根据存储在其中的值修改行为。

在运行时设置和更新自定义特性

在某些情况下,Apigee 正在处理 API 调用时,您可能希望 API 代理在运行时更新与访问令牌关联的元数据。为了帮助您做到这一点,Apigee 提供了用于获取和设置令牌属性的政策。如需了解详情,请参阅获取 OAuth V2 信息政策设置 OAuth V2 信息政策

在每项政策中,AccessToken 元素都应引用包含访问令牌的变量。