身份验证和授权是分别用于验证身份和资源访问权限的机制。本文档简要介绍了 Chat 应用和 Chat API 请求的身份验证和授权机制。
流程概览
下图显示了 Google Chat 的身份验证和授权的高级步骤：
配置 Google Cloud 项目、启用 Chat API 并配置 Chat 应用：在开发期间，您需要创建一个 Google Cloud 项目。在 Google Cloud 项目中，您可以启用 Chat API、配置 Chat 应用并设置身份验证。 如需了解详情，请参阅在 Google Workspace 上开发和构建 Chat 应用。
调用 Chat API：当应用调用 Chat API 时，它会向 Chat API 发送身份验证凭据。如果您的应用使用服务账号进行身份验证，则凭据会作为应用代码的一部分发送。如果您的应用需要使用尚未授予的用户身份验证来调用 Chat API，则会提示用户登录。
请求资源：您的应用会请求使用您在设置身份验证时指定的范围来访问资源。
征求用户同意：如果您的应用以用户身份进行身份验证，Google 会显示 OAuth 权限请求页面，以便用户决定是否授予您的应用对所请求数据的访问权限。使用服务账号进行身份验证不需要用户同意。
发送已获批准的资源请求：如果用户同意授权范围，您的应用会将凭据和用户批准的范围捆绑到请求中。该请求会发送到 Google 授权服务器，以获取访问令牌。
Google 返回访问令牌：访问令牌包含已授予的范围列表。如果返回的范围列表比请求的范围更受限，您的应用会关闭受令牌限制的所有功能。
访问所请求的资源：您的应用使用来自 Google 的访问令牌来调用 Chat API 并访问 Chat API 资源。
获取刷新令牌（可选）：如果您的应用必须在单个访问令牌的生命周期之外访问 Google Chat API，则可以获取刷新令牌。如需了解详情，请参阅使用 OAuth 2.0 访问 Google API。
请求更多资源：如果应用需要更多访问权限，它会要求用户授予新的范围，从而导致新的请求来获取访问令牌（步骤 3-6）。
聊天应用何时需要身份验证
Chat 应用可以发送消息来响应用户互动，也可以异步发送消息。它们还可以代表用户完成任务，例如创建 Chat 聊天室或获取 Chat 聊天室中的人员名单。
Chat 应用不需要进行身份验证即可响应用户互动，除非 Chat 应用在处理响应时调用 Chat API 或其他 Google API。
为了发送异步消息或代表用户执行任务，Chat 应用会向 Chat API 发出 RESTful 请求，这些请求需要进行身份验证和授权。
对用户互动的响应不需要进行身份验证
Google Chat 应用无需以用户或 Chat 应用的身份进行身份验证，即可同步接收和响应互动事件。
每当用户与 Google Chat 应用互动或调用 Google Chat 应用时，Google Chat 应用都会收到互动事件，包括以下情况：
- 用户向 Chat 应用发送消息。
- 用户 @提及某个 Chat 应用。
- 用户调用 Chat 应用的某个命令。
下图显示了 Chat 用户与 Chat 应用之间的请求-响应序列：
- 用户在 Google Chat 中向 Chat 应用发送消息。
- Google Chat 会将消息转发给该应用。
- 应用接收消息、处理消息，然后向 Google Chat 返回响应。
- Google Chat 会向用户或在聊天室中呈现回答。
此序列会针对每个 Chat 应用互动事件重复执行。
异步消息需要身份验证
当 Chat 应用向需要身份验证和授权的 Chat API 发出请求时，就会出现异步消息。
通过调用 Chat API，Chat 应用可以向 Google Chat 发布消息，或代表用户完成任务和访问数据。例如，在检测到服务器中断后，聊天应用可以调用 Chat API 来执行以下操作：
- 创建一个专门用于调查和修复中断问题的 Chat 聊天室。
- 将用户添加到 Chat 聊天室。
- 在 Chat 聊天室中发布消息，详细说明中断情况。
下图显示了 Chat 应用与 Chat 空间之间的异步消息序列：
- Chat 应用通过使用
spaces.messages.create方法调用 Chat API 来创建消息，并在 HTTP 请求中包含用户凭据。 - Google Chat 会使用服务账号或用户凭据对 Chat 应用进行身份验证。
- Google Chat 将应用的消息呈现到指定的 Chat 聊天室。
Chat API 范围
配置 OAuth 权限请求页面并选择范围，以定义向用户和应用审核者显示哪些信息，并注册应用以便以后发布。
如需定义授予应用的访问权限级别，您需要确定并声明授权范围。授权范围是一个 OAuth 2.0 URI 字符串，其中包含 Google Workspace 应用名称、应用访问的数据类型以及访问权限级别。
非敏感范围
| 范围代码 | 说明 |
|---|---|
https://www.googleapis.com/auth/chat.bot
|
允许 Chat 应用查看对话和发送消息。 |
敏感范围
| 范围代码 | 说明 |
|---|---|
https://www.googleapis.com/auth/chat.spaces
|
在 Chat 中创建对话和聊天室，以及查看或修改元数据（包括历史记录设置和访问权限设置）。 |
https://www.googleapis.com/auth/chat.spaces.create
|
在 Chat 中创建新对话。 |
https://www.googleapis.com/auth/chat.spaces.readonly
|
查看 Chat 中的聊天和聊天室。 |
https://www.googleapis.com/auth/chat.memberships
|
查看、更新和移除 Chat 对话中的成员以及向其中添加成员。 |
https://www.googleapis.com/auth/chat.memberships.app
|
在 Google Chat 对话中添加和移除自己。 |
https://www.googleapis.com/auth/chat.memberships.readonly
|
查看 Chat 对话中的成员。 |
https://www.googleapis.com/auth/chat.messages.create
|
在 Chat 中撰写和发送消息。 |
https://www.googleapis.com/auth/chat.messages.reactions
|
在 Chat 中查看、添加和删除对消息的回应。 |
https://www.googleapis.com/auth/chat.messages.reactions.create
|
在 Chat 中为消息添加回应。 |
https://www.googleapis.com/auth/chat.messages.reactions.readonly
|
查看对 Chat 中消息的回应。 |
https://www.googleapis.com/auth/chat.users.readstate
|
查看和修改 Chat 对话的上次读取时间。 |
https://www.googleapis.com/auth/chat.users.readstate.readonly
|
查看 Chat 对话的上次读取时间。 |
https://www.googleapis.com/auth/chat.admin.spaces.readonly
|
查看 Chat 中归管理员网域所有的聊天和聊天室。 |
https://www.googleapis.com/auth/chat.admin.spaces
|
在 Chat 中查看或修改管理员网域拥有的聊天和聊天室。 |
https://www.googleapis.com/auth/chat.admin.memberships.readonly
|
查看 Chat 中管理员网域拥有的对话中的成员和管理员。 |
https://www.googleapis.com/auth/chat.admin.memberships
|
查看、添加、更新和移除 Chat 中管理员网域拥有的对话中的成员和管理员。 |
https://www.googleapis.com/auth/chat.app.spaces
|
在 Chat 中创建对话和聊天室，以及查看或更新元数据（包括聊天记录设置和访问权限设置）。需要管理员审批。 |
https://www.googleapis.com/auth/chat.app.spaces.create
|
在 Chat 中创建新对话和聊天室。需要管理员审批。 |
https://www.googleapis.com/auth/chat.app.memberships
|
查看、添加、更新和移除 Chat 对话和聊天室中的成员。 需要管理员审批。 |
https://www.googleapis.com/auth/chat.customemojis
|
在 Chat 中查看、创建和删除自定义表情符号。 |
https://www.googleapis.com/auth/chat.customemojis.readonly
|
在 Chat 中查看自定义表情符号。 |
https://www.googleapis.com/auth/chat.users.spacesettings
|
查看和更新 Chat 用户聊天室设置。 |
受限范围
| 范围代码 | 说明 |
|---|---|
https://www.googleapis.com/auth/chat.delete
|
删除 Google Chat 中的对话和聊天室，并撤消对其中所关联文件的访问权限。 |
https://www.googleapis.com/auth/chat.import
|
将聊天室、消息和成员资格数据导入到 Chat。如需了解详情，请参阅授权 Chat 应用导入数据 |
https://www.googleapis.com/auth/chat.messages
|
查看、撰写、发送、更新和删除消息，以及添加、查看和删除对消息的回应。 |
https://www.googleapis.com/auth/chat.messages.readonly
|
在 Chat 中查看消息和回应。 |
https://www.googleapis.com/auth/chat.admin.delete
|
删除管理员网域拥有的对话和聊天室，并撤消对 Chat 中的关联文件的访问权限。 |
https://www.googleapis.com/auth/chat.app.delete
|
删除 Google Chat 中的对话和聊天室，并撤消对其中所关联文件的访问权限。 需要管理员审批。 |
上表中的范围根据以下定义指示了相应范围的敏感程度：
非敏感 - 这些范围提供的授权访问权限范围最小，仅需要进行基本应用验证。如需了解此要求，请参阅准备验证的步骤。
敏感 - 这些范围可让您的应用在获得用户授权后访问特定用户的 Google 数据。您需要完成额外的应用验证。如需了解此要求，请参阅请求敏感范围的应用的步骤。
受限 - 这些范围可广泛访问 Google 用户数据，因此您需要完成受限范围验证流程。如需了解此要求的相关信息，请参阅 Google API 服务：用户数据政策和针对特定 API 范围的其他要求。 另请参阅请求受限范围的应用的步骤。
如果您的应用需要访问任何其他 Google API，您也可以添加这些范围。如需详细了解 Google API 范围，请参阅使用 OAuth 2.0 访问 Google API。
如需详细了解 Google Workspace API 的范围，请参阅配置 OAuth 权限请求页面并选择范围。
必需的身份验证类型
Chat 应用可以通过以下两种方式使用 Chat API 进行身份验证和授权：
- 用户身份验证
- 用户身份验证可让聊天应用访问用户数据并代表用户完成操作。OAuth 范围用于指定已获授权的数据和操作。 除非 Chat 应用是由管理员安装的，或者已获得全网域授权，否则当 Chat 应用首次代表用户执行操作时，用户必须使用 OAuth 权限请求页面授权 Chat 应用。
- 应用身份验证
借助应用身份验证，Chat 应用可以使用服务账号凭据，并以自身身份访问数据和完成操作。由于 Chat 应用使用自己的凭据来访问和处理资源，因此最终用户无需批准 Chat 应用的 API 调用，并且您无法向 OAuth 意见征求屏幕添加支持应用授权的 OAuth 授权范围。
以下两种类型的 OAuth 授权范围支持应用身份验证：
https://www.googleapis.com/auth/chat.bot： 您的 Chat 应用可以调用支持此授权范围的 Google Chat API 方法，以创建、更新、获取、列出或删除其有权访问的资源，例如最终用户将您的 Chat 应用添加到其中的聊天室中的消息。 Chat 应用可以自行授予此授权范围，无需管理员或最终用户授权。https://www.googleapis.com/auth/chat.app.*（开发者预览版）：使用这些范围需要管理员一次性批准。如需获得管理员批准，您需要准备 Chat 应用的服务账号以接收管理员批准，具体方法是在 Google Workspace Marketplace SDK 中创建与 Google Workspace Marketplace 兼容的 OAuth 客户端并配置应用。这些范围允许您的 Chat 应用调用特定的 Google Chat API 方法。例如，chat.app.spaces.create允许应用创建 Chat 聊天室。
如果某个方法同时支持用户身份验证和应用身份验证，Chat API 会根据您使用的身份验证类型返回不同的结果：
- 通过应用身份验证，这些方法只会返回 Chat 应用可以访问的资源。
- 通过用户身份验证，这些方法只会返回用户可以访问的资源。
例如，使用应用授权调用 spaces.list() 方法会返回 Chat 应用所属的聊天室列表。使用用户授权调用 spaces.list() 会返回用户所属空间的列表。在实践中，您可能会在调用 Chat API 时同时使用这两种类型的身份验证，具体取决于 Chat 应用的设计和功能。
对于异步 Chat API 调用
下表列出了 Chat API 方法及其支持的授权范围：
| 方法 | 支持用户身份验证 | 支持应用身份验证 | 支持的授权范围 | |
|---|---|---|---|---|
| 聊天室 | ||||
| 创建聊天室 |
使用用户身份验证：
|
|||
| 设置聊天室 | — |
使用用户身份验证：
|
||
| 获取空间 |
使用用户身份验证：
|
|||
| 列出空间 |
使用用户身份验证：
|
|||
| 搜索空间 | — |
使用管理员权限进行用户身份验证：
|
||
| 更新空间 |
使用用户身份验证：
|
|||
| 删除聊天室 |
使用用户身份验证：
|
|||
| 完成空间的导入流程 | — |
使用用户身份验证：
|
||
| 查找私信 |
使用用户身份验证：
|
|||
| 成员 | ||||
| 创建会员 |
使用用户身份验证：
|
|||
| 成为会员 |
使用用户身份验证：
|
|||
| 列出会员 |
使用用户身份验证：
|
|||
| 删除会员 |
使用用户身份验证：
|
|||
| 更新会员 |
使用用户身份验证：
|
|||
| 信息 | ||||
| 创建消息 |
使用用户身份验证：
|
|||
| 接收消息 |
使用用户身份验证：
|
|||
| 列出消息 | — |
使用用户身份验证：
|
||
| 更新消息 |
使用用户身份验证：
|
|||
| 删除消息 |
使用用户身份验证：
|
|||
| 回应 | ||||
| 创建反应 | — |
使用用户身份验证：
|
||
| 列出回应 | — |
使用用户身份验证：
|
||
| 删除回应 | — |
使用用户身份验证：
|
||
| 自定义表情符号 | ||||
| 创建自定义表情符号 | — |
使用用户身份验证：
|
||
| 删除自定义表情符号 | — |
使用用户身份验证：
|
||
| 获取自定义表情符号 | — |
使用用户身份验证：
|
||
| 列出自定义表情符号 | — |
使用用户身份验证：
|
||
| 媒体和附件 | ||||
| 将媒体作为文件附件上传 | — |
使用用户身份验证：
|
||
| 下载媒体内容 |
使用用户身份验证：
|
|||
| 获取消息附件 | — |
如果选择应用身份验证：
|
||
| 用户读取状态 | ||||
| 获取用户的空间读取状态 | — |
使用用户身份验证：
|
||
| 更新用户的空间读取状态 | — |
使用用户身份验证：
|
||
| 获取用户的消息串已读状态 | — |
使用用户身份验证：
|
||
| 用户空间设置 | ||||
| 获取用户的聊天室通知设置 | — |
使用用户身份验证：
|
||
| 更新用户的聊天室通知设置 | — |
使用用户身份验证：
|
||
| YouTube 空间活动 | ||||
| 获取空间事件 | — |
使用用户身份验证时，您必须使用基于
事件类型的范围：
|
||
| 列出空间事件 | — |
使用用户身份验证时，您必须为请求中包含的每个
事件类型使用一个范围：
|
||
对于 Chat 应用互动事件
下表列出了用户与聊天应用的常见互动方式，以及是否需要或支持身份验证：
| 场景 | 无需进行身份验证 | 支持用户身份验证 | 支持应用身份验证 | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 接收来自以下来源的消息： |
|
|||||||||||||||
| 回复消息： |
|
|||||||||||||||
| 发送新消息： |
|
|||||||||||||||
相关主题
- 如需大致了解 Google Workspace 中的身份验证和授权，请参阅了解身份验证和授权。
- 如需大致了解 Google Cloud 中的身份验证和授权，请参阅身份验证概览。
- 如需详细了解服务账号，请参阅服务账号。
- 如需详细了解 Google API 如何使用 OAuth 2.0，请参阅使用 OAuth 2.0 访问 Google API。
- 使用用户凭据或服务账号设置身份验证和授权。