为 Claude Desktop 接入安全 Web 搜索：用 AgentCore Gateway 和 JWT 守住入口

2026-10-02 16 预计阅读时间: 1 分钟
来源: aws.amazon.com AI 摘要 Original link

Disclaimer: This article is an AI-assisted summary. Read it together with the original source when precision matters. The summary may omit context, version differences, or edge cases and is not official documentation.

预计阅读时间：11 分钟

Claude Desktop 使用 Amazon Bedrock 中的模型时，回答仍受模型知识截止时间限制。要让它查询实时网页，不能只把一个搜索 API 地址塞进提示词，而应把搜索能力封装成受控工具，并在桌面客户端与外部网络之间建立可认证、可审计的边界。

Amazon Bedrock AgentCore Gateway 可以承担这层边界：向 Claude Desktop 暴露工具接口，将调用转发给 Web 搜索目标，并通过 JWT 验证进入网关的请求。AWS IAM Identity Center 可负责员工身份登录，Amazon Cognito 则可用于 OAuth 流程和 JWT 签发。

网关不是搜索引擎，而是安全控制面

一条典型调用链可以设计成：

Claude Desktop
    │ MCP / HTTPS
    ▼
本地 OAuth 客户端或 MCP 连接器
    │ Authorization: Bearer <JWT>
    ▼
Amazon Bedrock AgentCore Gateway
    │ 经过授权的工具调用
    ▼
Web Search API、Lambda 或内部搜索服务

这里有三个边界需要分清：

  • 用户认证：确认发起请求的是哪位员工。Identity Center 适合承接组织账号与单点登录。
  • 令牌签发与验证：一种可落地的安排是让 Cognito 完成 OAuth 授权流程并签发 JWT，再让 AgentCore Gateway 验证签名、签发者、有效期和客户端声明。
  • 目标端凭证：搜索服务所需的 API Key、IAM 权限或其他凭证应由网关或后端持有，不能下发给 Claude Desktop。

因此，用户拿到的 JWT 只代表“允许调用搜索工具”，并不等于获得搜索供应商的密钥。撤销用户访问权、限制客户端和集中记录工具调用也会更容易。

把身份链路配置正确

具体控制台字段会随区域和服务版本变化，但配置时应围绕以下约束展开：

  1. 在 Cognito 中创建面向桌面应用的公共客户端，使用 Authorization Code + PKCE，不在客户端保存密钥。
  2. 按组织的身份体系，把 IAM Identity Center 登录接入相应的联合身份流程。
  3. 在 AgentCore Gateway 中配置 Cognito 的 JWT issuer 或 discovery 信息，并限制允许的客户端及 scope。
  4. 为搜索工具设置独立权限，例如 web-search/read，避免一个普通登录令牌获得所有网关工具的调用权。
  5. 将搜索 API 凭证保存在 Secrets Manager、目标 Lambda 的环境配置或其他服务端密钥存储中。

JWT 校验不能只做 Base64 解码。网关至少应检查：

  • 签名是否来自受信任的 JWKS；
  • iss 是否为预期签发者；
  • exp、nbf 等时间声明是否有效；
  • scope 或自定义权限声明是否包含搜索权限；
  • token 类型是否正确；
  • aud 或 client_id 是否与网关策略匹配。

尤其要注意，某些 Cognito access token 使用 client_id 表示客户端，而不一定按开发者预期提供 aud。策略应根据实际 token 类型配置，不能照搬 ID token 的校验规则。面向 API 调用时通常应使用 access token，而不是拿 ID token 代替授权凭证。

先用命令行验证网关

下面是一个可直接改造的冒烟测试。它假设网关提供 MCP 风格的 Streamable HTTP 入口，并支持无状态的 tools/call 请求。请把 GATEWAY_URL、JWT 和工具名替换成实际部署值；如果网关要求先执行 initialize 或维护 Mcp-Session-Id，则需要按返回头补充会话处理。

cat > test-web-search.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

: "${GATEWAY_URL:?Set GATEWAY_URL, for example https://gateway.example.com/mcp}"
: "${ACCESS_TOKEN:?Set ACCESS_TOKEN to a short-lived Cognito access token}"

payload='{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "web_search",
    "arguments": {
      "query": "Amazon Bedrock AgentCore Gateway latest documentation",
      "max_results": 5
    }
  }
}'

curl --fail-with-body --silent --show-error --no-buffer \
  --request POST "$GATEWAY_URL" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --data "$payload"
EOF

chmod +x test-web-search.sh
export GATEWAY_URL='https://replace-with-your-gateway.example/mcp'
export ACCESS_TOKEN='replace-with-a-short-lived-access-token'
./test-web-search.sh

测试时不要只检查 HTTP 200，还要确认三件事：无 token 返回 401，权限不足返回 403，合法 token 只能调用被允许的工具。如果过期 token 仍能成功，说明入口认证或缓存策略存在问题。

搜索工具最好返回结构化结果，而不是一整段无法追踪来源的文本。例如：

{
  "results": [
    {
      "title": "Result title",
      "url": "https://example.com/page",
      "snippet": "A short extract from the page",
      "published_at": "2025-01-15T09:00:00Z"
    }
  ]
}

稳定的 title、url、snippet 和时间字段能帮助模型生成引用，也便于后端去重和审计。

将网关接入 Claude Desktop

如果部署的 AgentCore Gateway 暴露 MCP 兼容端点，可以使用支持远程 MCP 的本地连接器。下面配置仅适合开发验证，假设本机已经安装 Node.js，并由 mcp-remote 将 Claude Desktop 的本地 stdio 调用转成远程 HTTPS 请求。

{
  "mcpServers": {
    "secure-web-search": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://replace-with-your-gateway.example/mcp",
        "--header",
        "Authorization: Bearer ${WEB_SEARCH_JWT}"
      ],
      "env": {
        "WEB_SEARCH_JWT": "replace-with-a-short-lived-access-token"
      }
    }
  }
}

不同版本连接器对环境变量展开和 OAuth 的支持可能不同，运行前应核对其参数格式。静态写入 JWT 只适合短时间联调，因为 token 到期后连接会失效，而且桌面配置文件可能被备份或同步。

生产环境更合理的方式是使用支持 Authorization Code + PKCE 的本地认证辅助程序：打开系统浏览器完成 Identity Center 登录，将 refresh token 放入操作系统钥匙串，并在调用网关前自动刷新 access token。不要把客户端密钥、搜索 API Key 或长期 refresh token直接写进 Claude Desktop 配置。

Web 搜索带来的风险不止是身份认证

JWT 保护的是“谁能调用工具”，却不能保证网页内容可信。搜索结果可能包含提示注入、恶意指令、虚假信息和诱导访问的 URL。建议在搜索目标或网关后端增加以下约束：

  • 只返回文本摘要和规范化 URL，不让网页内容直接控制工具调用；
  • 限制单次结果数、抓取大小、重定向次数和执行时间；
  • 对私有地址、云元数据地址和内网域名做出站拦截，防止 SSRF；
  • 对高风险域名使用允许列表或拒绝列表；
  • 在日志中记录用户、工具、时间、查询摘要和响应状态，但避免记录完整 JWT 与敏感查询；
  • 提示模型把网页视为不可信数据，并要求答案附带来源；
  • 对搜索供应商设置超时、重试上限、并发限制和成本配额。

还应把用户输入与工具参数分开验证。比如 max_results 应由服务端限制在一个合理范围内，不能因为模型传入 10000 就执行高成本抓取。

上线前检查清单

接入时可以按以下顺序推进：

  • [ ] 搜索目标只暴露必要参数，并返回带 URL 的结构化结果；
  • [ ] Cognito 桌面客户端启用 Authorization Code + PKCE，且不使用客户端密钥；
  • [ ] AgentCore Gateway 校验签名、issuer、有效期、客户端和 scope；
  • [ ] 无 token、错误 scope、过期 token 和错误 issuer 都有明确拒绝测试；
  • [ ] 搜索供应商凭证仅存在于服务端；
  • [ ] Claude Desktop 端具备安全的 token 刷新与本地存储机制；
  • [ ] 出站访问、速率、超时、结果数量和日志脱敏均有限制；
  • [ ] 模型回答保留来源，并明确区分搜索事实与模型推断。

这套设计的价值不只是让 Claude Desktop “能上网”。更重要的是，它把实时搜索变成一个有身份、有权限、有审计记录的企业工具。代价是需要维护 OAuth、令牌刷新和搜索目标，但相比把外部 API Key 直接交给桌面客户端，这个边界更清晰，也更适合组织内部推广。

# AI # AWS # LLM # 云平台 # 前端 # 机器学习

相关推荐