使用 JWT OAuth 令牌

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

本主题介绍如何使用 OAuthV2 政策生成、验证和刷新 JWT 访问令牌。

简介

JWT 操作允许 OAuthV2 政策生成、验证和刷新符合 IETF RFC 9068 标准的访问令牌，该标准规定了如何发布 JWT 格式的访问令牌。JWT 通常用于在连接的应用之间共享声明或断言。颁发 JWT 格式的 OAuthV2 访问令牌是颁发不透明访问令牌的替代方案。

在为 JWT 配置后，OAuthV2 政策会生成并返回 Base64 编码的 JWT，其中包含标头、载荷和以点分隔的签名。例如：

图 1：由标头、载荷和点分隔的签名组成的 JWT 序列化格式。

这些元素的编码内容取决于您配置 OAuthV2 政策的方式。在政策中，您可以指定诸如签名算法和载荷元素（如主题和名称）之类的参数。例如，标头可能解码为 {"alg":"HS256","typ":"at+JWT"}，而载荷可能解码为 {"sub":"ABC1234567","iat":1516239022}。

标头指定 typ 声明（始终为 "at+JWT）和 alg 声明，以指明用于为 JWT 签名的算法。Apigee 支持 RSA 和 HMAC 算法：RS(256,384,512) 和 HS(256,384,512)。

载荷

载荷包含有关实体的声明。某些声明必须在政策配置中提供，而其他声明由 Apigee 运行时自动生成。 该政策支持以下声明：

领取 说明 提供者
iss 令牌颁发者。此值按以下方式设置：(http|https)://{domain-name-for-proxy}/{proxy-basePath}。例如：https://api.mycompany.com/auth/v2。 Apigee
sub 客户端 ID 或资源所有者的 ID（在使用密码类型或授权许可类型的情况下）。如果请求中提供了 appEndUserId 参数，则该值将用作资源所有者 ID。您可以使用 OAuthV2 政策的 <AppEndUser> 元素控制设置此值的位置。 API 开发者
jti 唯一 ID，表示为基于 UUID 的随机字符串，用于唯一标识令牌。 Apigee
exp 过期时间，即令牌在此时间之后必须被视为无效。该值以纪元时间（以秒为单位）表示。 Apigee
iat 颁发时间（令牌的创建时间）。该值以纪元时间（以秒为单位）表示。 Apigee
client_id 客户端应用的唯一标识符。 API 开发者
scope 分配给令牌的 OAuth 范围。另请参阅使用 OAuth 范围。 API 开发者

签名

签名是使用编码标头、载荷、密钥/私钥和算法生成的。签名用于确保令牌的内容未被篡改。

如需详细了解 JWT 格式的 OAuth 2.0 访问令牌，请参阅 IETF RFC 9068：OAuth 2.0 访问令牌的 JSON 网络令牌 (JWT) 配置文件。

前提条件

本文档假定您了解如何使用 OAuthV2 政策生成和验证 OAuthV2 访问令牌。无论您是使用 JWT 操作还是创建不透明字符串令牌的传统操作，OAuthV2 政策的基本用法都相同。您可以将 JWT 访问令牌与所有受支持的 OAuthV2 许可类型搭配使用。另请参阅 OAuth 2.0 简介。

生成

使用 GenerateJWTAccessToken 和 GenerateJWTAccessTokenImplicitGrant 操作通过 OAuthV2 政策生成 JWT 访问令牌。这些操作类似于政策的传统 GenerateAccessToken 和 GenerateAccessTokenImplicitGrant 操作。两者的主要区别在于 JWT 操作返回 JWT 格式的访问令牌，而不是不透明的字符串令牌。另请参阅获取 OAuth 2.0 令牌。

以下示例展示了如何在 OAuthV2 政策中使用这些操作。这些示例使用 client_credentials 许可类型：但是，您可以在这些操作中使用任何受支持的许可类型。

生成使用 HMAC 算法进行签名的 JWT 格式令牌

使用 HMAC (HS256/HS384/HS512) 算法之一指定 <Algorithm> 元素。另外请提供 <SecretKey>。 以下示例显示了一个政策，该政策配置为使用指定的密钥来生成使用 HS512 算法签名的 JWT。

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

生成使用 RSA 算法进行签名的 JWT 格式令牌

在 <Algorithm> 元素中指定某个 RSA 算法（RS256/RS384/RS512 之一），并在 <PrivateKey> 元素中提供私钥。以下示例显示了一个政策，该政策配置为使用 RS256 算法来生成使用 RSA 私钥签名的 JWT。

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

使用隐式授权类型生成 JWT 格式令牌

GenerateJWTAccessTokenImplicitGrant 操作生成使用隐式许可类型的 JWT 访问令牌。它会自动为令牌提供隐式许可类型；因此，<SupportedGrantTypes> 元素不是必需的。 由于它是 JWT，<Algorithm> 元素是必需的。以下示例显示了 RS256 算法的用法。因此，<PrivateKey> 元素是必需的。另请参阅使用隐式授权类型。

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessTokenImplicitGrant</Operation>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

正在验证

使用 VerifyJWTAccessToken 操作验证采用 OAuthV2 政策的 JWT 访问令牌。此操作类似于 VerifyAccessToken 操作：区别在于 VerifyJWTAccessToken 应用于 JWT 格式的令牌，而 VerifyAccessToken 应用于不透明令牌。

验证使用 HMAC 算法签名的 JWT 访问令牌

以下示例展示了如何配置 OAuthV2 政策以验证使用 HS512 算法签名的 JWT 令牌。将 VerifyJWTAccessToken 操作与 HMAC 算法搭配使用时，政策配置必须使用 <SecretKey> 元素指定用于为 JWT 签名的密钥。

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
</OAuthV2>

验证使用 RSA 算法签名的 JWT 访问令牌

以下示例展示了如何配置 OAuthV2 政策以验证使用 RS512 算法签名的 JWT 令牌。在使用采用了 RSA 算法的 VerifyJWTAccessToken 操作时，政策配置必须使用 <PublicKey> 元素来指定与用于为 JWT 签名的私钥相对应的公钥。

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>RS512</Algorithm>
  <PublicKey>
    <Value ref="propertyset.non-secrets.rsa-publickey-1"/>
  </PublicKey>
</OAuthV2>

刷新

使用 RefreshJWTAccessToken 操作来刷新 JWT 访问令牌。此操作类似于政策的传统 RefreshAccessToken 操作。另请参阅刷新访问令牌。

刷新 HMAC 签名的访问令牌

以下政策示例展示了如何配置 OAuthV2 政策以刷新使用 HMAC 算法签名的 JWT 令牌。在这种情况下，<SecretKey> 和 <Algorithm> 元素是必需的。

刷新操作的响应类似于新生成的令牌的响应。刷新操作会生成新的 JWT 令牌并更新过期时间，使其他声明保持不变。

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>HS512</Algorithm>
    <SecretKey>
      <Value ref="private.mysecretkey"/>
    </SecretKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

刷新 RSA 签名的 JWT 访问令牌

以下政策示例展示了如何配置 OAuthV2 政策以刷新使用 RSA 算法签名的 JWT 令牌。另请参阅刷新访问令牌。

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>RS256</Algorithm>
    <PrivateKey>
      <Value ref="private.rsa-privatekey-1"/>
    </PrivateKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

示例令牌响应

对于生成和刷新操作，响应正文类似于以下示例。请注意，access_token 表示为序列化 JWT，刷新令牌是传统的不透明格式令牌。

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImF0K0pXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "developer.email": "developer@example.org",
  "token_type": "Bearer",
  "issued_at": "1658352381404",
  "expires_in": 1799,
  "refresh_token": "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "refresh_token_issued_at": "1658352381404",
  "refresh_token_expires_in": 86399,
  "refresh_token_status": "Approved",
  "refresh_count": "0",
  "organization_name": "cerruti",
  "api_product_list_json": [ "TestingProduct" ]
}

必需的政策元素摘要

下表介绍了上述示例中使用的 JWT 特定元素：

元素 类型 备注
算法 静态值 指定用于签署令牌的算法。
SecretKey 引用值 提供用于验证或签署使用 HMAC 算法的令牌的密钥：HS HS (256/384/512)。
PrivateKey 引用值 提供用于生成令牌的私钥。仅在算法是 RSA 算法时使用：RS (256/384/512)。
PublicKey 引用值 提供用于验证令牌的公钥。仅在算法是 RSA 算法时使用：RS (256/384/512)。

不支持的政策元素

JWT 令牌配置不支持以下 OAuthV2 政策元素：

元素 备注
ExternalAuthorization 生成 JWT 访问令牌时，OAuthV2 政策将验证客户端 ID 和密钥。
ExternalAccessToken 生成 JWT 访问令牌时，令牌将由 Apigee 签名，声明将由 Apigee 默认提供或政策配置提供。 该政策支持 ExternalRefreshToken，这可帮助迁移用例。
RFCCompliantRequestResponse 默认情况下，JWT 访问令牌的生成和刷新均符合 RFC 规范。

使用说明

  • 不支持加密 JWT。
  • 除了 JWT 访问令牌之外，政策响应还包含支持刷新令牌的许可类型的不透明刷新令牌。只有密码类型和授权代码许可类型支持刷新令牌。
  • 在发送给包含 OAuthV2 政策的代理的请求中添加 Authorization 标头。
  • 您无法撤消 JWT 访问令牌。生成的 JWT 令牌将在过期之前保持有效。您可以撤消与 JWT 访问令牌关联的刷新令牌。
  • 访问令牌的生成、验证和刷新必须由 Apigee 处理。虽然有权访问公钥或密钥的外部应用或网关可以解码 JWT 的内容，但外部应用没有 client_id 声明识别的 API 产品的相关信息，因此无法在 API 代理授权中起作用。