令牌代理是 Omnichannel Gateway 的核心架构组件，可为面向公众的聊天界面（特别是 WebChat）提供安全、受管理型身份验证
本文档介绍了什么是令牌代理，为什么必须使用令牌代理而不是不进行身份验证，以及在使用 Omnichannel Gateway 时令牌代理如何管理安全会话。
什么是令牌代理？
当您将聊天小部件（例如 WebChat）部署到面向公众的网站上时，最终用户需要在浏览器中与您的后端智能体互动。在客户端直接公开您的虚拟客服存在许多风险：
- 无法控制会话令牌生命周期
- 无法控制谁可以获得会话和令牌，例如仅限网站的登录用户
- 没有中间方可以调整参数
令牌代理 充当安全中间资源，您可以对其进行配置，以允许使用支持此流程的机制。公共 WebChat SDK 不会允许所有智能体以未经身份验证的方式进行对话，而是会与令牌代理通信以获取短期有效的会话锁定访问令牌，然后可以使用该令牌与您的智能体进行对话。
配置令牌代理
如需配置最小 令牌代理，您可以定义令牌代理资源，指定显示名称和颁发者服务帐号。例如：
{
"displayName": "A broker",
"issuerServiceAccount": "YOUR_BROKER_SERVICE_ACCOUNT_HERE"
}
issuerServiceAccount 是您授予 IAM 权限的服务帐号（例如 roles/agenticapplications.user）。当 Web 聊天连接启动时，我们会检查此权限，以验证令牌代理是否有权创建会话并与您的智能体通信。
如需详细了解如何在 Web 聊天上下文中使用代理，请参阅使用预构建的 SDK 配置 WebChat。如需配置 reCAPTCHA 验证等高级功能，请参阅自定义令牌代理。
使用代理而不是允许未经身份验证的流量的原因
虽然理论上可以允许匿名访问智能体，但这样做会带来严重的安全和运营风险：
- 滥用防护和配额： 如果没有身份验证，互联网上的任何人都可以向您的虚拟客服发送垃圾信息，耗尽您的 API 配额并产生大量费用。
- 会话隔离： 代理可确保每位访问者都有自己的加密隔离聊天会话，防止用户窃听或劫持其他用户的聊天。
- 访问控制政策： 经过身份验证的令牌允许系统在 API 网关级别验证请求，让您可以立即撤消会话或屏蔽可疑活动。
因此，Omnichannel Gateway 不允许匿名访问智能体，并且强制执行至少最基本的安全功能，例如会话锁定。
WebChat 会话的生命周期
信息：本部分是针对我们提供的预构建 WebChat 而定制的，但任何自定义实现看起来都非常相似。
当用户访问托管 WebChat 小部件的网页时，预构建的 SDK 会与令牌代理协调安全握手，以获取凭据并维护聊天流。
下图展示了此端到端生命周期，包括初始令牌授予、会话绑定和定期令牌刷新：
概括来讲，身份验证和对话流程包括以下阶段：
- WebChat SDK 向令牌代理请求新会话，令牌代理会验证该请求并返回唯一的会话 ID，以及短期有效的访问令牌和刷新令牌。访问令牌与配置的
issuerServiceAccount相关联。 - SDK 使用访问令牌连接到 Omnichannel Gateway；网关会验证令牌的有效性和会话完整性，如果令牌已过期或会话 ID 无效，则拒绝访问。
- 连接被接受后，系统会打开全双工通信流，让用户和网关可以无缝交换消息，而无需将令牌附加到各个消息。
- 在访问令牌过期之前，SDK 会主动使用刷新令牌从令牌代理获取新的会话锁定访问令牌，如果刷新令牌已过期或被撤消，则会自动清除会话并重新启动流程。
详细了解令牌的生命周期
为了保持高安全性，颁发的授权凭据使用双令牌系统：
- 初始颁发： 当用户开始新的聊天会话时，WebChat SDK 会调用令牌代理的
issueToken端点，并将授予类型设置为REFRESH_TOKEN。令牌代理会生成唯一的会话 ID 和安全的长效刷新令牌。此刷新令牌的安全哈希存储在后端数据库中，令牌本身会与初始的短期有效访问令牌一起返回给客户端。 - 短期有效访问令牌： 访问令牌是结构化的 JSON Web 令牌 (JWT)，默认情况下会在 15 分钟 后过期。您可以在配置令牌代理 (
tokenExpiry) 时将此时间配置为最多一小时。客户端 SDK 会自动检查令牌过期时间，并根据需要以静默方式执行 刷新。 - 定期后台刷新： 在当前访问令牌过期前大约一分钟，客户端 SDK 会调用代理的
issueToken端点，并将授予类型设置为ACCESS_TOKEN和安全的refreshToken。代理会验证刷新令牌并返回新的访问令牌，而不会中断用户正在进行的聊天会话。 - 刷新令牌过期和管理： 为了确保最大安全性，长效刷新令牌有自己的过期时间。虽然短期有效访问令牌的生命周期可以直接在令牌代理资源上配置，但 Omnichannel Gateway 会管理长效刷新令牌的生命周期：在刷新请求期间，网关会根据其存储的哈希验证令牌，并检查其过期时间戳。如果刷新令牌已过期，网关会拒绝该请求，并提示客户端 SDK 清除会话并重新启动令牌握手。
- 撤消刷新令牌： 您可以使用令牌代理的
revokeRefreshTokenAPI 端点，通过提供令牌的唯一 ID 来立即使活跃会话失效。撤消对于安全和会话管理至关重要，例如当用户退出 Web 应用时、检测到可疑或滥用聊天行为时，或者用户设备遭到入侵时。撤消后，网关会阻止任何后续的后台刷新尝试，并立即终止聊天会话。
客户端应在打开聊天会话时同时提供会话 ID 和访问令牌。由于这些声明直接嵌入到已签名的 JWT 载荷中，因此Omnichannel Gateway 会验证并强制执行使用此令牌发送的消息仅映射到特定的锁定会话 ID。即使恶意方拦截了用户活跃的 JWT 访问令牌，他们也无法使用该令牌来仿冒或访问任何其他用户的会话。
安全地设置颁发者服务帐号
令牌代理利用指定的颁发者服务账号 对 JWT 访问令牌进行签名和铸造。为了保持强大的安全态势，请务必为此服务帐号配置一组最低权限。从您的代理获取访问令牌的每个用户都将获得对此服务帐号的授予，并且有权以该用户的身份行事。
- 客户端浏览器应用只需要发送和接收智能体聊天消息的权限。因此，
- 我们建议，用于
issuerServiceAccount的服务帐号的角色仅被授予omnichannelEndpointConfigs.interact。
后续步骤
- 请参阅自定义令牌代理指南，以实现更高级的会话和身份验证架构。