使用自定义方法对用户进行身份验证

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

要对用户进行身份验证，客户端应用程序必须将 HTTP 请求的授权标头中的 JSON Web 令牌（JWT）发送到您的后端 API。Extensible Service Proxy（ESP）代表您的 API 验证令牌，因此您无需在API中添加任何代码即可处理身份验证。不过，您需要配置 OpenAPI 文档以支持您选择的身份验证方法。

ESP 使用 JWT 颁发者的公钥高效地验证 JWT。ESP 缓存公钥 5 分钟。此外，ESP 会缓存经过验证的 JWT 五分钟或直到 JWT 到期，以先发生者为准。

准备工作

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

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

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

OpenAPI 文档中必须包含安全要求对象和安全性定义对象，ESP 才能验证签名的 JWT 中的声明。

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

  1. 将以下代码添加到 OpenAPI 文档中的安全性定义中：

     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: []

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

不需要 x-google-audiences 字段。ESP 在 aud 声明中接受所有 https://SERVICE_NAME 格式的后端服务名称的 JWT。要允许其他客户端 ID 访问后端服务，您可以使用以逗号分隔的值在 x-google-audiences 字段中指定允许的客户端 ID。然后，ESP 会在 aud 声明中接受任何具有指定客户端 ID 的 JWT。

ESP 支持 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。

如果省略 x-google-jwks_uri，ESP 将遵循 OpenID Connect Discovery 协议自动发现给定 OpenID 提供商的 JWKS URI。ESP 将向 x-google-issuer/.well-known/openid-configuration 发送请求，解析 JSON 响应，以及从顶级 jwks_uri 字段读取 JWKS URI。

请注意，省略 x-google-jwks_uri 会导致较长的冷启动时间，因为 ESP 必须在启动时进行额外的远程调用。因此，如果 JWKS URI 经常发生更改，建议您仅省略此字段。 大多数认证的 OpenID 提供商（例如 Google、Auth0 和 Okta）拥有稳定的 JWKS URI。

您还可以通过添加 x-google-extensions 来自定义 JWT 位置。如需了解详情，请参阅 openAPI 扩展程序。

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

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

curl -H "Authorization: Bearer ${TOKEN}" "${ENDPOINTS_HOST}/echo"

其中 ENDPOINTS_HOST 和 TOKEN 分别是包含 API 主机名和身份验证令牌的环境变量。请参阅向 Endpoints API 发出经过身份验证的请求。表示使用 Authorization:Bearer 标头发送请求的示例代码。

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

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

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

ESP 通常会转发收到的所有标头。但是，当后端地址由 OpenAPI 规范中的 x-google-backend 或 gRPC 服务配置中的 BackendRule 指定时，它会替换原来的 Authorization 标头。

ESP 会将 X-Endpoint-API-UserInfo 中的身份验证结果发送到后端 API。我们建议您使用此标头，而不是原来的 Authorization 标头。此标头是一个字符串。base64url对 JSON 对象进行编码。ESPv2 和 ESP 的 JSON 对象格式有所不同。对于 ESPv2，JSON 对象恰好是原始 JWT 载荷。对于 ESP，JSON 对象使用不同的字段名称，并将原始 JWT 载荷放在 claims 字段下。如需详细了解格式，请参阅处理后端服务中的 JWT。

后续步骤