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

本页介绍如何在 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 中的声明。

适用于 Google Cloud Endpoints 的 Okta 集成指南中所述,您对 OpenAPI 文档进行了以下更改:

  1. 将以下代码添加到 OpenAPI 文档中的安全性定义中。将 YOUR_OKTA_TENANT_NAME 替换为您的 Okta 租户的名称,将 YOUR_OKTA_CLIENT_ID 替换为您在 Okta 租户中创建的客户端 ID。

              securityDefinitions:
                okta_jwt:
                  authorizationUrl: ""
                  flow: "implicit"
                  type: "oauth2"
                  x-google-issuer: "https://YOUR_OKTA_TENANT_NAME.com"
                  x-google-jwks_uri: "https://YOUR_OKTA_TENANT_NAME.com/oauth2/v1/keys"
                  x-google-audiences: "YOUR_OKTA_CLIENT_ID"
        
  2. 在 API 级别添加安全性部分以应用于整个 API,或在方法级别应用以应用于特定方法。

      security:
            - okta_jwt: []
        

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

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

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

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

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

其中 ENDPOINTS_HOSTTOKEN 分别是包含 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 对象。

    {
      "id": "from-sub",
      "issuer": "from-iss",
      "email": "from-email",
      "audiences": ["from-aud"],
      "claims": {
         original-jwt-payload
       }
    }
    

如果您使用的是 ESPv2 Beta 版,则标头中的值格式会有所不同。有关新格式的详情,请参阅迁移到 Extensible Service Proxy V2 Beta版

后续步骤