自定义令牌代理

本指南提供了有关如何为全渠道网关配置、自定义和扩展令牌代理的更高级信息。

高级令牌代理概念

在自定义令牌代理之前，请务必阅读并了解令牌代理架构和安全模型。

安全令牌代理（第三方令牌代理）

默认情况下，令牌代理以公开模式 (public_issue_method_config) 运行，这允许客户端 SDK 直接连接并请求未经身份验证的会话令牌。虽然公共模式非常适合基本部署，但它仅允许有限的自定义和可调选项（本页将介绍这些选项）。例如，由于公共模式代理不安全且从用户浏览器发出，因此无法在公共模式代理上注入经过身份验证的元数据（例如最终用户的已验证账号标识符）或有条件地控制令牌发放。

为了支持经过身份验证的网络聊天会话，您可以将令牌代理配置为安全模式，以与自定义令牌代理搭配使用。

当令牌代理以安全模式配置时：

  • 网关会拒绝向未经身份验证的 issueToken 端点发送的公开请求（不含有效的刷新令牌）。

  • 允许从后端向 issueTrustedToken 端点发送经过身份验证的请求。这些请求可以在用户会话中填充私密且经过验证的值。

保护令牌代理配置

如需将令牌代理配置为拒绝公开请求，请在令牌代理资源上设置 secured_issue_method_config issue 方法：

{
  "displayName": "Secured Account Broker",
  "issuerServiceAccount": "YOUR_BROKER_SERVICE_ACCOUNT_HERE",
  "securedIssueMethodConfig": {}
}

实现第三方令牌代理端点

您的后端充当安全的中介代理。它应向您的前端应用公开一个端点。当您的前端请求安全聊天令牌时，后端会执行以下操作：

  1. 执行任何用户身份验证检查（例如，验证平台上的 Cookie、会话或身份令牌）。

  2. 执行任何速率限制或防滥用验证。

  3. 在您想要批准请求时，从后端调用网关的 issueTrustedToken 方法，传递可信的声明来表示已验证的会话上下文。

调用 issueTrustedToken API

从后端服务中，调用由具有 agenticapplications.omnichannelTokenBrokers.issueTrusted 权限的 Google Cloud 服务账号签名的 issueTrustedToken API：

Node.js

使用官方 Google Auth 库，通过服务账号凭据自动对请求进行身份验证：

const { GoogleAuth } = require('google-auth-library');

async function issueTrustedToken() {
  const auth = new GoogleAuth({
    scopes: ['https://www.googleapis.com/auth/cloud-platform']
  });
  const client = await auth.getClient();
  const tokenBrokerName = "projects/PROJECT_ID/locations/LOCATION/omnichannelTokenBrokers/TOKEN_BROKER_ID";
  const url = `https://agenticapplications.googleapis.com/v1alpha/${tokenBrokerName}:issueTrustedToken`;

  const response = await client.request({
    url,
    method: 'POST',
    data: {
      trustedFields: {
        user_id: 'cust_9817231',
        loyalty_tier: 'gold'
      }
    }
  });

  return response.data;
}

Python

使用标准身份验证辅助模块通过本地环境应用凭据对 HTTP POST 请求进行签名：

import google.auth
from google.auth.transport.requests import AuthorizedSession

def issue_trusted_token():
    credentials, project = google.auth.default(
        scopes=['https://www.googleapis.com/auth/cloud-platform']
    )
    authed_session = AuthorizedSession(credentials)

    token_broker_name = "projects/PROJECT_ID/locations/LOCATION/omnichannelTokenBrokers/TOKEN_BROKER_ID"
    url = f'https://agenticapplications.googleapis.com/v1alpha/{token_broker_name}:issueTrustedToken'

    response = authed_session.post(
        url,
        json={
            'trustedFields': {
                'user_id': 'cust_9817231',
                'loyalty_tier': 'gold'
            }
        }
    )
    response.raise_for_status()
    return response.json()

curl

直接通过命令行执行通用 HTTP POST 请求，以测试代理配置：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://agenticapplications.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/omnichannelTokenBrokers/TOKEN_BROKER_ID:issueTrustedToken" \
  -d '{
    "trustedFields": {
      "user_id": "cust_9817231",
      "loyalty_tier": "gold"
    }
  }'
响应正文

网关会返回短期有效的访问令牌、会话 ID 和刷新令牌参数：

{
  "accessToken": "ACCESS_TOKEN_STRING",
  "expireTime": "2026-05-26T20:26:00Z",
  "sessionId": "SESSION_ID_STRING",
  ...
}

您的端点必须将整个响应往返发送回客户端浏览器 SDK。您不应尝试检查或后处理此载荷，因为从现在开始，此载荷归网关和 Web 客户端所有并由其管理。

与 WebChat 集成

将预构建的 WebChat SDK 与安全令牌代理集成时，您必须提供自定义令牌解析器，而不是仅提供 tokenBrokerName。自定义解析器负责调用后端授权端点来获取令牌。

如需配置自定义令牌解析器，请在 createContext 的 tokenBroker 选项中提供 initialAccessTokenResolver：

<script>
  window.addEventListener("chat-messenger-loaded", >async () = {
    // Custom resolver function to fetch the token from your 3P broker
    const customTokenResolver = >async () = {
      const response = await fetch("https://api.yourdomain.com/chat/auth-token", {
        method: "POST",
        headers: {
          "Content-Type": "application/json"
        },
        body: JSON.stringify({
          // Pass any clientside parameters if needed
        })
      });

      if (!response.ok) {
        throw new Error("Failed to authenticate chat session");
      }
      return response.json();
    };

    const context = await window.chatSdk.prebuilts.omnichannel.createContext({
      tokenBroker: {
        tokenBrokerName: "projects/PROJECT_ID/locations/LOCATION/omnichannelTokenBrokers/TOKEN_BROKER_ID",
        initialAccessTokenResolver: customTokenResolve<r
     > }
    });

    window.chatSdk.registerContext(context);
  });
/script

WebChat SDK 使用您的自定义解析器成功初始化会话后，后端操作会根据请求类型而有所不同：

  • 初始发放：WebChat SDK 调用自定义 initialAccessTokenResolver 以获取初始令牌。这会在客户端上设置安全会话 ID、初始访问令牌和刷新令牌。
  • 后台令牌刷新：WebChat SDK 会在后台自动管理令牌过期问题。在访问令牌过期前大约一分钟，SDK 会直接向面向公众的网关端点发送刷新请求。它会传递 refreshToken 并指定授权类型 ACCESS_TOKEN。由于此流程已通过预签名 refreshToken 授权，因此 SDK 不会再次调用您的自定义解析器进行后台刷新。

后续步骤