对用户进行身份验证

本页面介绍如何使用 Cloud Endpoints Frameworks 在您的 API 中添加对于通过客户端应用进行用户身份验证的支持。请注意,目前支持 Android 和 JavaScript 客户端。

Endpoints Frameworks 支持通过使用以下任何方法的客户端应用对用户进行身份验证:

无论您使用哪种身份验证方法,在需要检查身份验证是否正确的每种 API 方法中,都必须检查是否存在有效的 User,具体如以下部分所述:

前提条件

本页面假定您已经完成以下操作:

使用 Firebase 身份验证进行身份验证

要支持使用 Firebase 身份验证的客户端发起的调用,请执行以下操作:

  1. 创建一个 Firebase 项目(如果您尚未创建)。Firebase 项目是使用 Firebase 服务的 Google Cloud 控制台项目。如需了解详情,请参阅 Firebase 项目介绍Firebase 文档

  2. 将以下操作所提到的参数添加到您的 @Api 或方法注释中:

    • 向注释添加 authenticators 参数,将其设置为值 {EspAuthenticator.class}
    • 添加一个 issuers 参数,其中包含设置为 Firebase 的 @ApiIssuer
    • 添加一个 issuerAudiences 参数,其中包含设置为 Firebase 的 @ApiIssuerAudience 和您的项目 ID。

    例如:

    @Api(
        name = "YOUR_API_NAME",
        version = "VERSION_NUMBER",
        authenticators = {EspAuthenticator.class},
        issuers = {
            @ApiIssuer(
                name = "firebase",
                issuer = "https://securetoken.google.com/YOUR_PROJECT_ID",
                jwksUri = "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com")
        },
        issuerAudiences = {
            @ApiIssuerAudience(name = "firebase", audiences = "YOUR_PROJECT_ID")
        })
    
    • YOUR_API_NAME 替换为您的 API 名称。
    • VERSION_NUMBER 替换为您的 API 版本,例如 v1
    • YOUR_PROJECT_ID 的两个实例替换为您的 Firebase 项目 ID。
  3. 在您的 API 实现代码中,导入 Users

    import com.google.api.server.spi.auth.common.User;
    
  4. 在需要检查身份验证是否正确的每种 API 方法中,检查是否存在有效的 User,如果不存在,则引发异常,具体如以下方法定义示例中所示:

    @ApiMethod(httpMethod = ApiMethod.HttpMethod.GET)
    public Email getUserEmail(User user) throws UnauthorizedException {
      if (user == null) {
        throw new UnauthorizedException("Invalid credentials");
      }
    
      Email response = new Email();
      response.setEmail(user.getEmail());
      return response;
    }
    
  5. 每当添加新客户端时,您都需要重新部署 API

向客户端添加 Firebase 身份验证

Firebase 文档所述,您可以向代码中添加 Firebase 身份验证。客户端必须具有与之关联的 Google Cloud 项目,并且项目 ID 必须列在 API 的 Firebase issuer 配置中,具体如上述部分所示。

使用 Auth0 进行身份验证

要支持使用 Auth0 的客户端发起的调用,请执行以下操作:

  1. 将以下操作所提到的参数添加到您的 @Api 或方法注释中:

    • 向注释添加 authenticators 参数,将其设置为值 {EspAuthenticator.class}
    • 添加一个 issuers 参数,其中包含设置为 Auth0 的 @ApiIssuer
    • 添加一个 issuerAudiences 参数,其中包含设置为 Auth0 的 @ApiIssuerAudience 和您的 Auth0 客户端 ID。

    例如:

    @Api(
        name = "YOUR_API_NAME",
        version = "VERSION_NUMBER",
        authenticators = {EspAuthenticator.class},
        issuers = {
            @ApiIssuer(
                name = "auth0",
                issuer = "https://YOUR_ACCOUNT_NAME.auth0.com/",
                jwksUri = "https://YOUR_ACCOUNT_NAME.auth0.com/.well-known/jwks.json")
         },
         issuerAudiences = {
             @ApiIssuerAudience(name = "auth0", audiences = "AUTH0_CLIENT_ID")
        })
    
    • YOUR_API_NAME 替换为您的 API 名称。
    • VERSION_NUMBER 替换为您的 API 版本,例如 v1
    • YOUR_ACCOUNT_NAME 替换为用于客户端的 Auth0 账号名称。
    • AUTH0_CLIENT_ID 替换为您要用于客户端的 ID。
  2. 在您的 API 实现代码中,导入 Users

    import com.google.api.server.spi.auth.common.User;
    
  3. 在需要检查身份验证是否正确的每种 API 方法中,检查是否存在有效的 User,如果不存在,则引发异常,具体如以下方法定义示例中所示:

    @ApiMethod(httpMethod = ApiMethod.HttpMethod.GET)
    public Email getUserEmail(User user) throws UnauthorizedException {
      if (user == null) {
        throw new UnauthorizedException("Invalid credentials");
      }
    
      Email response = new Email();
      response.setEmail(user.getEmail());
      return response;
    }
    
  4. 每当添加新客户端时,您都需要重新部署 API

向客户端添加 Auth0 身份验证

Auth0 文档所述,您可以向代码中添加 Auth0 身份验证。客户端必须列在 API 的 Auth0 issuer 配置中。

使用 Google ID 令牌进行身份验证

要支持使用 Google ID 令牌进行身份验证的客户端发起的调用,请执行以下操作:

  1. 获取每个客户端应用的 OAuth 2 客户端 ID。客户端应用所有者必须通过 Google Cloud 控制台生成客户端 ID。有关说明,请参阅创建客户端 ID

  2. 在您的 @Api 注释中,添加一个对应于您要授予访问权限的每个客户端应用的 clientIds 条目(其中包含客户端 ID),并添加对应于每个 Android 客户端的 audiences 条目。

    例如:

    @Api(
       name = "YOUR_API_NAME",
       version = "VERSION_NUMBER",
       clientIds = {"YOUR_CLIENT_ID"},
       audiences = {"YOUR_CLIENT_ID"}
    )
    
    • YOUR_API_NAME 替换为您的 API 名称。
    • VERSION_NUMBER 替换为您的 API 版本,例如 v1
    • YOUR_CLIENT_ID 替换为在客户端应用项目中生成的 OAuth 2 客户端 ID。
  3. 在您的 API 实现代码中,导入 Users

    import com.google.api.server.spi.auth.common.User;
    
  4. 在需要检查身份验证是否正确的每种 API 方法中,检查是否存在有效的 User,如果不存在,则抛出异常,具体如以下方法定义示例中所示:

    @ApiMethod(httpMethod = ApiMethod.HttpMethod.GET)
    public Email getUserEmail(User user) throws UnauthorizedException {
      if (user == null) {
        throw new UnauthorizedException("Invalid credentials");
      }
    
      Email response = new Email();
      response.setEmail(user.getEmail());
      return response;
    }
    
  5. 每当添加新客户端时,您都需要重新部署 API

向客户端添加 Google ID 令牌身份验证

如需了解如何向客户端添加身份验证代码,请参阅以下内容:

发送客户端中的 JWT

如果您在客户端中使用 JWT 向 API 发送经过身份验证的请求,则 JWT 必须位于 HTTP 请求的 Authorization 标头中。JWT 应具备以下必要的声明:

  • iss
  • sub
  • aud
  • iat
  • exp

后续步骤

如需了解用户身份验证及其与 API 密钥授权的不同之处的背景信息,请参阅何时及为何使用 API 密钥