验证来自 Google Chat 的请求

对于基于 HTTP 端点构建的 Google Chat 应用，本部分介绍了如何验证对您的端点的请求是否来自 Chat。

为了将互动事件分派到 Chat 应用的端点，Google 会向您的服务发出请求。为了验证请求是否来自 Google，Chat 会在发送到端点的每个 HTTPS 请求的 Authorization 标头中添加一个令牌载荷。例如：

POST
Host: yourappurl.com
Authorization: Bearer AbCdEf123456
Content-Type: application/json
User-Agent: Google-Dynamite

在上例中，字符串 AbCdEf123456 是 Bearer 授权令牌。这是 Google 生成的加密令牌。载荷令牌的类型和 audience 字段的值取决于您在配置 Chat 应用时选择的身份验证受众群体类型。

如果您使用 Cloud Functions 或 Cloud Run 实现了 Chat 应用，Cloud IAM 会自动处理令牌验证。您只需将 Google Chat 服务账号添加为授权调用方即可。如果您的应用实现了自己的 HTTP 服务器，您可以使用开源 Google API 客户端库验证您的 Bearer 令牌：

如果令牌未针对 Chat 应用进行验证，您的服务应使用 HTTPS 响应代码 401 (Unauthorized) 对请求做出响应。

使用 Cloud Functions 或 Cloud Run 对请求进行身份验证

如果您的函数逻辑是使用 Cloud Functions 或 Cloud Run 实现的，您必须在 Chat 应用连接设置的身份验证受众群体字段中选择 HTTP 端点网址，并确保配置中的 HTTP 端点网址与 Cloud Functions 或 Cloud Run 端点的网址相对应。

然后，您需要将 Google Chat 服务账号 chat@system.gserviceaccount.com 授权为调用方。

以下步骤展示了如何使用 Cloud Functions（第 1 代）：

控制台

将函数部署到 Google Cloud 后：

  1. 在 Google Cloud 控制台中，转到 Cloud Functions 页面：

    转到 Cloud Functions

  2. 在 Cloud Functions 列表中，点击接收函数旁边的复选框。（请勿点击函数本身。）

  3. 点击屏幕顶部的权限。此时权限面板会打开。

  4. 点击添加主账号。

  5. 在新的主账号字段中，输入 chat@system.gserviceaccount.com。

  6. 从选择角色下拉菜单中选择 Cloud Functions > Cloud Functions Invoker 角色。

  7. 点击保存。

gcloud

使用 gcloud functions add-iam-policy-binding 命令：

gcloud functions add-iam-policy-binding RECEIVING_FUNCTION \
  --member='serviceAccount:chat@system.gserviceaccount.com' \
  --role='roles/cloudfunctions.invoker'

将 RECEIVING_FUNCTION 替换为 Chat 应用函数的名称。

以下步骤展示了如何使用 Cloud Functions（第 2 代）或 Cloud Run 服务：

控制台

将函数或服务部署到 Google Cloud 后：

  1. 在 Google Cloud 控制台中，转到 Cloud Run 页面。

    转到 Cloud Run

  2. 在 Cloud Run 服务列表中，点击接收函数旁边的复选框。（请勿点击函数本身。）

  3. 点击屏幕顶部的权限。此时权限面板会打开。

  4. 点击添加主账号。

  5. 在新的主账号字段中，输入 chat@system.gserviceaccount.com。

  6. 从选择角色下拉菜单中依次选择 Cloud Run > Cloud Run Invoker 角色。

  7. 点击保存。

gcloud

使用 gcloud functions add-invoker-policy-binding 命令：

gcloud functions add-invoker-policy-binding RECEIVING_FUNCTION \
  --member='serviceAccount:chat@system.gserviceaccount.com'

将 RECEIVING_FUNCTION 替换为 Chat 应用函数的名称。

使用 ID 令牌对 HTTP 请求进行身份验证

如果 Chat 应用连接设置的“Authentication Audience”（身份验证受众群体）字段设置为 HTTP 端点网址，则请求中的 Bearer 授权令牌是 Google 签名的 OpenID Connect (OIDC) ID 令牌。email 字段设置为 chat@system.gserviceaccount.com。 Authentication Audience 字段设置为您配置 Google Chat 向 Chat 应用发送请求的网址。例如，如果 Chat 应用的配置端点为 https://example.com/app/，则 ID 令牌中的 Authentication Audience 字段为 https://example.com/app/。

如果您的 HTTP 端点未托管在支持基于 IAM 的身份验证的服务（例如 Cloud Functions 或 Cloud Run）上，则建议使用此身份验证方法。使用此方法时，您的 HTTP 服务需要其所运行端点的网址信息，但不需要 Cloud 项目编号信息。

以下示例展示了如何验证 Bearer 令牌是否由 Google Chat 签发，以及是否使用 Google OAuth 客户端库定位到您的应用。

Java

java/basic-app/src/main/java/com/google/chat/app/basic/App.java
String CHAT_ISSUER = "chat@system.gserviceaccount.com";
JsonFactory factory = JacksonFactory.getDefaultInstance();

GoogleIdTokenVerifier verifier =
    new GoogleIdTokenVerifier.Builder(new ApacheHttpTransport(), factory)
        .setAudience(Collections.singletonList(AUDIENCE))
        .build();

GoogleIdToken idToken = GoogleIdToken.parse(factory, bearer);
return idToken != null
    && verifier.verify(idToken)
    && idToken.getPayload().getEmailVerified()
    && idToken.getPayload().getEmail().equals(CHAT_ISSUER);

Python

python/basic-app/main.py
# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

try:
    # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
    request = requests.Request()
    token = id_token.verify_oauth2_token(bearer, request, AUDIENCE)
    return token['email'] == CHAT_ISSUER

except:
    return False

Node.js

node/basic-app/index.js
// Bearer Tokens received by apps will always specify this issuer.
const chatIssuer = 'chat@system.gserviceaccount.com';

// Verify valid token, signed by chatIssuer, intended for a third party.
try {
  const ticket = await client.verifyIdToken({
    idToken: bearer,
    audience: audience
  });
  return ticket.getPayload().email_verified
      && ticket.getPayload().email === chatIssuer;
} catch (unused) {
  return false;
}

使用项目编号 JWT 对请求进行身份验证

如果 Chat 应用连接设置的“Authentication Audience”（身份验证受众群体）字段设置为 Project Number，则请求中的 Bearer 授权令牌是自签名的 JSON Web 令牌 (JWT)，由 chat@system.gserviceaccount.com 签发和签名。audience 字段设置为您用于构建 Chat 应用的 Google Cloud 项目编号。例如，如果 Chat 应用的 Cloud 项目编号为 1234567890，则 JWT 中的 audience 字段为 1234567890。

仅当您更倾向于使用 Cloud 项目编号（而非 HTTP 端点网址）来验证请求时，才建议使用此身份验证方法。例如，如果您想随着时间的推移更改端点网址，同时保持 Cloud 项目编号不变；或者，如果您想为多个 Cloud 项目编号使用相同的端点，并想将 audience 字段与 Cloud 项目编号列表进行比较。

以下示例展示了如何使用 Google OAuth 客户端库验证 Bearer 令牌是否由 Google Chat 签发并定位到您的项目。

Java

java/basic-app/src/main/java/com/google/chat/app/basic/App.java
String CHAT_ISSUER = "chat@system.gserviceaccount.com";
JsonFactory factory = JacksonFactory.getDefaultInstance();

GooglePublicKeysManager keyManagerBuilder =
    new GooglePublicKeysManager.Builder(new ApacheHttpTransport(), factory)
        .setPublicCertsEncodedUrl(
            "https://www.googleapis.com/service_accounts/v1/metadata/x509/" + CHAT_ISSUER)
        .build();

GoogleIdTokenVerifier verifier =
    new GoogleIdTokenVerifier.Builder(keyManagerBuilder).setIssuer(CHAT_ISSUER).build();

GoogleIdToken idToken = GoogleIdToken.parse(factory, bearer);
return idToken != null
    && verifier.verify(idToken)
    && idToken.verifyAudience(Collections.singletonList(AUDIENCE))
    && idToken.verifyIssuer(CHAT_ISSUER);

Python

python/basic-app/main.py
# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

try:
    # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
    request = requests.Request()
    certs_url = 'https://www.googleapis.com/service_accounts/v1/metadata/x509/' + CHAT_ISSUER
    token = id_token.verify_token(bearer, request, AUDIENCE, certs_url)
    return token['iss'] == CHAT_ISSUER

except:
    return False

Node.js

node/basic-app/index.js
// Bearer Tokens received by apps will always specify this issuer.
const chatIssuer = 'chat@system.gserviceaccount.com';

// Verify valid token, signed by CHAT_ISSUER, intended for a third party.
try {
  const response = await fetch('https://www.googleapis.com/service_accounts/v1/metadata/x509/' + chatIssuer);
  const certs = await response.json();
  await client.verifySignedJwtWithCertsAsync(
    bearer, certs, audience, [chatIssuer]);
  return true;
} catch (unused) {
  return false;
}