入站认证

入站认证验证进入智能体的请求方身份。VeADK 支持 API Key 与 OAuth2 两类方式。

API Key 认证

API Key 通过唯一字符串密钥验证请求方身份、授权访问 API 资源。VeADK 约定将 API Key 放在 URL 的 token 参数中传递。

API Key 仅适用于 A2A / MCP Server 部署模式，不建议在 VeADK Web 部署模式中使用；后者更推荐 OAuth2。

在脚手架创建智能体时选择 API Key 认证，或为已有项目在部署时加上 --auth-method=api-key 启用。此后用户访问应用时，API 网关会校验 token URL 参数中携带的 API Key。

OAuth2 单点登录

OAuth2 是一套开放的授权框架，通过令牌而非直接暴露账号密码，实现第三方应用对资源的有限访问；用户一次登录后即可免重复验证地访问多个关联应用。VeADK 提供两种接入方式：

方式	适用场景	说明
API 网关模式	VeFaaS 云端部署	通过脚手架部署，由 API 网关处理认证
Starlette / FastAPI 中间件	本地开发 / 自托管	在应用内集成 OAuth2 中间件

API 网关模式

适用于通过 VeFaaS 部署的 VeADK Web 应用，由 API 网关处理 OAuth2 流程。

API 网关模式需要 4.0.0 及以上版本的 API 网关。

在脚手架创建智能体时选择 OAuth2，或为已有项目在部署时加上 --auth-method=oauth2；VeADK 会自动创建 Identity 用户池与客户端。若要复用已有资源，部署时用 --user-pool-name 与 --client-name 指定。部署后在 Agent Identity 中创建用户：

进入用户池

登录火山引擎控制台，进入 Agent Identity 服务，在左侧选择 身份认证 › 用户池管理，选择用户池。

新建用户

在用户池的用户标签页点击 新建用户，填写信息并确定。

用户访问应用时，API 网关会引导其完成登录；登录后可从 Authorization 请求头取得用户的 JWT 令牌。

Starlette / FastAPI 中间件

适用于本地开发或自托管部署，通过 VeADK 提供的中间件在应用内处理 OAuth2，支持所有基于 Starlette 的框架（含 FastAPI）。推荐用 OAuth2Config.from_veidentity() 自动配置 VeIdentity 用户池：

from fastapi import FastAPI
from veadk.auth.middleware.oauth2_auth import OAuth2Config, setup_oauth2

app = FastAPI()

setup_oauth2(
    app,
    OAuth2Config.from_veidentity(
        user_pool_name="my-app",
        client_name="my-app-web",
        redirect_uri="https://myapp.com/oauth2/callback",
    ),
)

该方法会自动创建用户池与客户端（如不存在）、注册回调 URL 并配置 OAuth2 端点。Starlette 用法相同，将 FastAPI() 换成 Starlette() 即可。复用已有资源时关闭自动创建：

setup_oauth2(
    app,
    OAuth2Config.from_veidentity(
        user_pool_name="existing-pool",
        client_name="existing-client",
        redirect_uri="https://myapp.com/oauth2/callback",
        auto_create=False,             # 资源不存在时报错
        auto_register_callback=False,  # 不修改回调 URL
    ),
)

本地开发需关闭 HTTPS cookie：

setup_oauth2(
    app,
    OAuth2Config.from_veidentity(
        user_pool_name="my-app",
        client_name="my-app-web",
        redirect_uri="http://localhost:8000/oauth2/callback",
        cookie_secure=False,  # 本地 HTTP 开发
    ),
)

接入非 VeIdentity 的 OAuth2 提供商时，直接构造 OAuth2Config：

setup_oauth2(
    app,
    OAuth2Config(
        authorize_url="https://provider.com/oauth2/authorize",
        token_url="https://provider.com/oauth2/token",
        userinfo_url="https://provider.com/oauth2/userinfo",
        client_id="your-client-id",
        client_secret="your-client-secret",
        redirect_uri="https://myapp.com/oauth2/callback",
    ),
)

中间件会自动注册以下路由：

路由	说明
`/oauth2/login`	发起 OAuth2 登录
`/oauth2/callback`	处理 OAuth2 回调
`/oauth2/logout`	登出并清除会话
`/oauth2/userinfo`	获取当前用户信息

可配置跳过认证的路径：exempt_paths=["/health", "/metrics"]（精确匹配）、exempt_prefixes=["/public/", "/static/"]（前缀匹配）。中间件按请求类型响应：浏览器请求重定向到登录页，API 请求返回 401。API 请求通过 Accept: application/json 请求头、路径前缀（默认 /api/）或 X-Requested-With: XMLHttpRequest 识别，可用 api_path_prefixes 自定义。 OAuth2Config.from_veidentity() 关键参数：

参数	默认值	说明
`user_pool_name`	必填	VeIdentity 用户池名称
`client_name`	必填	用户池客户端名称
`redirect_uri`	必填	OAuth2 回调 URL
`auto_create`	`True`	资源不存在时自动创建
`auto_register_callback`	`True`	自动注册回调 URL
`client_type`	`WEB_APPLICATION`	客户端类型
`scope`	`"openid profile email"`	OAuth2 作用域

OAuth2Config 关键参数：

参数	默认值	说明
`session_timeout_seconds`	`3600`	会话超时（秒）
`cookie_secure`	`True`	是否启用安全 cookie
`auto_refresh_token`	`True`	自动刷新令牌
`token_refresh_threshold_seconds`	`300`	令牌刷新阈值（秒）
`api_path_prefixes`	`["/api/"]`	API 路径前缀

默认的 InMemoryStateStore 仅适用于单进程部署。分布式场景需实现基于 Redis 等外部存储的 state store，并通过 setup_oauth2(app, config, state_store=...) 传入。

OAuth2 JWT 认证

OAuth2 JWT 认证将 OAuth2 授权框架与 JWT 结合，用 JWT 承载授权令牌，适用于 A2A / MCP Server。在脚手架创建智能体时选择 OAuth2，或为已有项目在部署时加上 --auth-method=oauth2；VeADK 会自动创建 Identity 用户池，需要复用时用 --user-pool-name 指定。随后在 Agent Identity 的用户池中新建 M2M 类型客户端，用其凭据换取 JWT 令牌：

REGION="cn-beijing"
USER_POOL_ID="FILL_IN_YOUR_USER_POOL_ID"
CLIENT_ID="FILL_IN_YOUR_CLIENT_ID"
CLIENT_SECRET="FILL_IN_YOUR_SECRET"

curl --location "https://userpool-${USER_POOL_ID}.userpool.auth.id.${REGION}.volces.com/oauth/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "Authorization: Basic $(echo -n "${CLIENT_ID}:${CLIENT_SECRET}" | base64)" \
  --data-urlencode "grant_type=client_credentials"

用户访问应用时，API 网关校验其携带的 JWT 令牌；令牌可从 Authorization 请求头取得。

向下游 A2A 智能体传递令牌

当 AgentKit A2A Registry 已启用，且当前智能体需要调用 Registry 中的下游智能体时，VeADK 1.0.3 可以沿调用链传递以下入站凭证：

入站凭证	下游请求头	行为
`X-Ve-TIP-Token`	`X-Ve-TIP-Token`	将可信身份传播令牌传给下游 A2A 智能体。
`Authorization: Bearer <token>`	`Authorization`	当下游 Agent Card 声明 OAuth2 时，优先使用调用方的 Bearer Token。
`X-Forwarded-Authorization` 或 `X-Original-Authorization`	`Authorization`	网关保留原始 Bearer Token 时，将其恢复为下游 `Authorization` 请求头。

只有 Bearer 形式的 Authorization 值会被传递。若下游 OAuth2 请求使用入站 JWT 后返回 401，VeADK 会尝试使用下游 Agent Card 中的 M2M OAuth2 配置重新获取令牌并重试一次。在无法从入站请求取得 TIP Token 的任务中，也可以通过环境变量显式配置。以下名称按顺序兼容，推荐使用第一个：

export REGISTRY_UPSTREAM_TIP_TOKEN="${TIP_TOKEN}"

兼容名称包括 AGENTKIT_UPSTREAM_TIP_TOKEN、A2A_REGISTRY_UPSTREAM_TIP_TOKEN、VE_TIP_TOKEN、X_VE_TIP_TOKEN 与 TIP_TOKEN。

JWT 与 TIP Token 代表调用方身份。只应向受信任的下游智能体传递，并确保日志、错误信息和追踪数据不会记录令牌值。

概览

快速开始

核心组件

可观测

扩展

前端

安全

API Key 认证

OAuth2 单点登录

API 网关模式

Starlette / FastAPI 中间件

OAuth2 JWT 认证

向下游 A2A 智能体传递令牌

​API Key 认证

​OAuth2 单点登录

​API 网关模式

​Starlette / FastAPI 中间件

​OAuth2 JWT 认证

​向下游 A2A 智能体传递令牌

API Key 认证

OAuth2 单点登录

API 网关模式

Starlette / FastAPI 中间件

OAuth2 JWT 认证

向下游 A2A 智能体传递令牌