对用户进行身份验证

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

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

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

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

前提条件

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

已创建 Google Cloud 项目。
添加 API 管理。

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

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

创建一个 Firebase 项目（如果您尚未创建）。Firebase 项目是使用 Firebase 服务的 Google Cloud 控制台项目。如需了解详情，请参阅 Firebase 项目介绍和 Firebase 文档。
将以下操作所提到的参数添加到您的 @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。

在您的 API 实现代码中，导入 Users：

import com.google.api.server.spi.auth.common.User;

在需要检查身份验证是否正确的每种 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;
}

每当添加新客户端时，您都需要重新部署 API。

向客户端添加 Firebase 身份验证

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

使用 Auth0 进行身份验证

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

将以下操作所提到的参数添加到您的 @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。

在您的 API 实现代码中，导入 Users：

import com.google.api.server.spi.auth.common.User;

在需要检查身份验证是否正确的每种 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;
}

每当添加新客户端时，您都需要重新部署 API。

向客户端添加 Auth0 身份验证

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

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

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

获取每个客户端应用的 OAuth 2 客户端 ID。客户端应用所有者必须通过 Google Cloud 控制台生成客户端 ID。有关说明，请参阅创建客户端 ID。
在您的 @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。

在您的 API 实现代码中，导入 Users：

import com.google.api.server.spi.auth.common.User;

在需要检查身份验证是否正确的每种 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;
}

每当添加新客户端时，您都需要重新部署 API。

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

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

Android 应用

发送客户端中的 JWT

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

iss
sub
aud
iat
exp

后续步骤

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