使用 JWT 对用户进行身份验证

本页介绍如何在 API Gateway 中支持用户身份验证。

要对用户进行身份验证，客户端应用程序必须将 HTTP 请求的授权标头中的 JSON Web 令牌（JWT）发送到您的后端 API。API Gateway 代表 API 验证令牌，因此您无需在 API 中添加任何代码即可处理身份验证。但是，您需要为网关配置 API 配置来支持您选择的身份验证方法。

API Gateway 使用 JWT 颁发者的 JSON Web 密钥集 (JWKS) 高效地验证 JWT。JWKS 的位置在网关 API 配置的 x-google-jwks_uri 字段中指定。API Gateway 会缓存 JWKS 五分钟，并且每五分钟刷新一次。

准备工作

  • 根据身份验证方法提供的文档，将身份验证代码添加到客户端应用。

  • 当客户端应用发送 HTTP 请求时，请求中的授权标头必须包含以下 JWT 声明：
    • iss（颁发者）
    • sub（主题）
    • aud（受众群体）
    • iat（颁发时间）
    • exp（到期时间）

配置 API Gateway 以支持客户端身份验证

API 配置中必须有安全要求对象和安全性定义对象，API Gateway 才能验证签名的 JWT 中的声明。

要支持 JWT 身份验证，请执行以下操作：

  1. 将以下内容添加到 API 配置中的安全定义中，该定义遵循 OpenAPI 2.0 安全方案：

     securityDefinitions:
   your_custom_auth_id:
     authorizationUrl: ""
     flow: "implicit"
     type: "oauth2"
     # The value below should be unique
     x-google-issuer: "issuer of the token"
     x-google-jwks_uri: "url to the public key"
     # Optional. Replace YOUR-CLIENT-ID with your client ID
     x-google-audiences: "YOUR-CLIENT-ID"

  2. 在 API 级别添加安全性部分以应用于整个 API，或在方法级别应用以应用于特定方法。

     security:
   - your_custom_auth_id: []

您可以在 API 配置中定义多个安全性定义，但每个定义都必须有不同的颁发者。如果同时在 API 级层和方法级层使用 security 部分，则方法级层的设置将覆盖 API 级层的设置。

x-google-audiences 字段不是必需字段。API Gateway 接受所有具有后端服务名称（格式为 aud 声明中的 https://SERVICE_NAME。

要允许其他客户端 ID 访问后端服务，您可以指定 x-google-audiences 字段中允许使用的客户端 ID 逗号分隔值。然后，API Gateway 会接受 JWT 在 aud 声明中指定客户端 ID。

x-google-jwks_uri 是必填字段。API Gateway 支持 x-google-jwks_uri OpenAPI 扩展程序定义的两种非对称公钥格式：

  • JWK 集格式。 例如：
    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • X509。例如：
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

如果您使用的是对称密钥格式，请将 x-google-jwks_uri 设置为包含 base64url 编码密钥字符串的文件的 URI。

向 API Gateway API 发出经过身份验证的调用

使用身份验证令牌发送请求时，我们建议您将令牌放在 Authorization:Bearer 标头中。例如：

curl --request POST \
  --header "Authorization: Bearer ${TOKEN}" \
  "${GATEWAY_URL}/echo"

其中，GATEWAY_URL 和 TOKEN 分别是包含已部署网关网址和身份验证令牌的环境变量。请参阅向 API Gateway API 发出经过身份验证的请求，查看使用 Authorization:Bearer 标头发送请求的示例代码。

如果在发送请求时无法使用标头，可以将身份验证令牌放在名为 access_token 的查询参数中。例如：

curl "${GATEWAY_URL}/echo?access_token=${TOKEN}"

在 API 中接收经过验证的结果

API Gateway 通常会转发它收到的所有标头。但是，当后端地址由 API 配置中的 x-google-backend 指定时，它会替换原来的 Authorization 标头。

API Gateway 会将 X-Apigateway-Api-Userinfo 中的身份验证结果发送到后端 API。我们建议您使用此标头，而不是原来的 Authorization 标头。此标头采用 base64url 编码，并且包含 JWT 载荷。

后续步骤