入站认证

入站认证验证进入智能体的请求方身份。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 的调用链中，VeADK 可以把当前请求携带的身份凭证传递给下游智能体，使下游继续按原用户身份和信任关系执行授权。

身份凭证会发送给解析到的下游 A2A 地址。仅调用可信的下游智能体，并为传入令牌配置完成任务所需的最小权限。

入站凭证	下游行为
`X-Ve-TIP-Token`	使用相同的请求头透传给下游 A2A 智能体。
`Authorization: Bearer <JWT>`	当下游 AgentCard 声明 OAuth2 时，优先把 Bearer JWT 作为下游的 `Authorization` 请求头。其他认证方案不会作为用户 JWT 透传。

对于声明 OAuth2 的下游智能体，VeADK 先使用透传的 Bearer JWT 发起请求。只有下游明确返回 401 Unauthorized 时，才会改用 OAuth2 M2M 令牌重试一次。其他状态码或调用错误不会触发 M2M 回退，避免把业务错误或服务故障误判为身份令牌失效。

技能沙箱中的身份透传

execute_skills 在调用技能沙箱时同样会将入站身份凭证转发给沙箱。VeADK 从凭证服务中读取凭证键为 inbound_auth 的入站凭证，并以 inbound_auth 请求头发送到沙箱的 A2A 端点，使沙箱中的工作流能够以原始用户身份执行。若当前请求未携带入站凭证，则不附加该请求头。详见代码沙箱中的技能沙箱执行部分。

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

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 调用中的身份透传

技能沙箱中的身份透传