入站认证

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

本节的 from_veidentity(client_secret=...) 直接复用方式、A2A 1.0 AgentCard 和托管 API Key 解析属于未发布的 Preview，按以下源码版本核验；VeADK 1.1.13 不包含这些增量。需要这些能力时，可在独立虚拟环境中安装该版本

pip install "veadk-python @ git+https://github.com/volcengine/veadk-python.git@adcdfdcc6a5a213b249a8caad435b939c01df7f6"

API Key 认证

URL 参数可能进入浏览器历史、访问日志和转发链路。只通过 HTTPS 传递凭据，并对 URL 日志脱敏；密钥验证通过后仍需按用户权限限制资源访问

API Key 通过唯一字符串密钥验证请求方身份、授权访问 API 资源。本节的 VeFaaS API 网关部署使用 URL 的 token 参数传递 API Key；其他服务的认证方式应按对应 API 文档配置。

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 用户池：示例依赖 fastapi 和 uvicorn，先运行 pip install fastapi uvicorn 安装。每个应用只调用一次 setup_oauth2()；后续片段是替代配置，不应依次追加到同一应用准备已有用户池和 Web 客户端，预先登记 http://localhost:8000/oauth2/callback。设置 OAUTH2_USER_POOL_NAME、OAUTH2_CLIENT_NAME，并为运行进程提供有权读取这些资源的云凭据。示例仅用于本地 HTTP 调试；上线后使用 HTTPS 并恢复 cookie_secure=True

app.py

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

app = FastAPI()

@app.get("/api/profile")
async def profile():
    return {"authenticated": True}

setup_oauth2(
    app,
    OAuth2Config.from_veidentity(
        user_pool_name=os.environ["OAUTH2_USER_POOL_NAME"],
        client_name=os.environ["OAUTH2_CLIENT_NAME"],
        redirect_uri="http://localhost:8000/oauth2/callback",
        auto_create=False,
        auto_register_callback=False,
        cookie_secure=False,
    ),
)

保存为 app.py，运行 uvicorn app:app --host 127.0.0.1 --port 8000。未登录时，访问 /api/profile 应返回 401；浏览器访问 /oauth2/login 完成登录后，再访问该接口应返回 authenticated: true from_veidentity() 默认允许创建不存在的资源并登记回调，示例将这两项关闭。需要自动创建时应先确认资源创建权限与回调地址。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 开发
    ),
)

通过 UID 复用已有用户池和客户端时，可同时提供 client_uid 与 client_secret，跳过启动时的客户端查询：

setup_oauth2(
    app,
    OAuth2Config.from_veidentity(
        user_pool_uid="pool-xxxx",
        client_uid="client-xxxx",
        client_secret=os.environ["OAUTH2_CLIENT_SECRET"],
        redirect_uri="https://myapp.com/oauth2/callback",
        auto_create=False,
    ),
)

接入非 VeIdentity 的提供商时，直接构造 OAuth2Config。以下替代配置片段适用于签发 JWT 访问令牌的提供商；先按提供商的 OpenID Connect 元数据设置各端点、签发者与公钥集环境变量，并将 OAUTH2_AUDIENCE 设为该 API 接受的令牌受众。不要把任意客户端 ID 当作受众

setup_oauth2(
    app,
    OAuth2Config(
        authorize_url=os.environ["OAUTH2_AUTHORIZE_URL"],
        token_url=os.environ["OAUTH2_TOKEN_URL"],
        userinfo_url=os.environ["OAUTH2_USERINFO_URL"],
        issuer=os.environ["OAUTH2_ISSUER"],
        jwks_uri=os.environ["OAUTH2_JWKS_URI"],
        audience=os.environ["OAUTH2_AUDIENCE"],
        client_id=os.environ["OAUTH2_CLIENT_ID"],
        client_secret=os.environ["OAUTH2_CLIENT_SECRET"],
        redirect_uri="https://myapp.com/oauth2/callback",
    ),
)

直接构造时不会自动发现 jwks_uri；缺少公钥集配置会导致 JWT 校验无法完成。提供商签发不透明访问令牌时，改用 use_introspection=True 并设置 introspection_url，按提供商要求提供内省客户端凭据中间件会自动注册以下路由：

路由	说明
`/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 自定义。

应用集成参数

setup_oauth2() 返回管理 OAuth2 流程的 OAuth2Handler，并注册认证路由与中间件

参数	类型	默认值	说明
`app`	`Starlette`	必填	Starlette 或 FastAPI 应用
`config`	`OAuth2Config`	必填	认证配置
`routes`	`OAuth2RoutePaths / None`	`None`	自定义登录、回调、登出和用户信息路径；默认使用上表中的路径
`exempt_paths`	`Iterable[str] / None`	`None`	免认证的精确路径
`exempt_prefixes`	`Iterable[str] / None`	`None`	免认证的路径前缀
`state_store`	`StateStore / None`	`None`	OAuth state 存储；默认使用进程内存

例如，在已创建 app 与 config 后，可用以下片段替换原 setup_oauth2() 调用。config.redirect_uri 和提供商登记的回调必须同步改为新的回调地址

from veadk.auth.middleware.oauth2_auth import OAuth2RoutePaths

setup_oauth2(
    app,
    config,
    routes=OAuth2RoutePaths(
        login="/auth/login",
        callback="/auth/callback",
        logout="/auth/logout",
        userinfo="/auth/userinfo",
    ),
    exempt_paths=["/health"],
    exempt_prefixes=["/public/"],
)

VeIdentity 配置参数

OAuth2Config.from_veidentity() 参数如下。省略 session_timeout_seconds 时，会尝试使用客户端配置的刷新令牌有效期；读取不到时保留 OAuth2Config 默认值

参数	类型	默认值	说明
`user_pool_name`	`str / None`	`None`	用户池名称；名称与 UID 至少提供一项
`user_pool_uid`	`str / None`	`None`	用户池 UID，优先于名称
`client_name`	`str / None`	`None`	客户端名称；名称与 UID 至少提供一项
`client_uid`	`str / None`	`None`	客户端 UID，优先于名称
`client_secret`	`str / None`	`None`	未发布的 Preview 参数；与 client_uid 一同提供时跳过客户端密钥查询
`redirect_uri`	`str`	必填	OAuth2 回调 URL
`auto_create`	`bool`	`True`	按名称创建不存在的用户池和客户端；仅提供 UID 时不会创建
`auto_register_callback`	`bool`	`True`	将回调 URL 登记到客户端
`client_type`	`UserPoolClientType`	`WEB_APPLICATION`	新建客户端的类型
`web_origin`	`str / None`	`None`	回调登记使用的 Web Origin；未设置时从 redirect_uri 提取
`scope`	`str`	`"openid profile email"`	以空格分隔的授权范围
`identity_client`	`IdentityClient / None`	`None`	使用指定的 Identity 客户端；未设置时使用全局配置或默认客户端
`**extra_config`	`Any`	—	其他 OAuth2Config 参数，如 cookie_secure、use_pkce 和 session_timeout_seconds；不重复传入已由服务发现设置的端点参数

OAuth2Config 参数

端点与授权请求

参数	类型	默认值	说明
`authorize_url`	`str`	必填	授权端点 URL
`token_url`	`str`	必填	令牌端点 URL
`client_id`	`str`	必填	提供商登记的客户端 ID
`client_secret`	`str / None`	`None`	客户端密钥；公开客户端可不设置
`redirect_uri`	`str`	必填	与客户端登记值一致的回调 URL
`scope`	`str`	`"openid profile"`	以空格分隔的授权范围
`response_type`	`str`	`"code"`	授权响应类型；本集成使用授权码流程
`extra_authorize_params`	`dict[str, str]`	`{}`	附加到授权请求的参数
`extra_token_params`	`dict[str, str]`	`{}`	附加到令牌请求的参数
`extra_token_headers`	`dict[str, str]`	`{}`	令牌请求的附加请求头
`use_pkce`	`bool`	`False`	启用 PKCE，需提供商支持
`userinfo_url`	`str / None`	`None`	用户信息端点；未配置时不请求该端点
`end_session_url`	`str / None`	`None`	提供商的登出端点
`logout_redirect_url`	`str`	`"/"`	登出后重定向地址
`user_id_field`	`str`	`"sub"`	从用户信息中提取用户标识的字段
`user_id_cookie_name`	`str`	`"veadk_user_id"`	保存用户标识的 Cookie 名称

参数	类型	默认值	说明
`session_cookie_name`	`str`	`"veadk_session"`	保存会话的 Cookie 名称
`session_timeout_seconds`	`int`	`3600`	浏览器会话的绝对有效期，单位为秒
`cookie_secure`	`bool`	`True`	仅允许通过 HTTPS 发送 Cookie
`cookie_samesite`	`str`	`"lax"`	Cookie 的 SameSite 策略
`cookie_domain`	`str / None`	`None`	Cookie 域；未设置时由浏览器限定为当前主机
`cookie_path`	`str`	`"/"`	Cookie 的路径范围
`cookie_signing_secret`	`str / None`	`None`	会话签名密钥；未设置时使用 client_secret
`auto_refresh_token`	`bool`	`True`	有可用刷新令牌时自动刷新访问令牌
`token_refresh_threshold_seconds`	`int`	`300`	访问令牌到期前开始刷新的时间，单位为秒

访问令牌校验

参数	类型	默认值	说明
`issuer`	`str / None`	`None`	预期令牌签发者；按提供商元数据配置
`jwks_uri`	`str / None`	`None`	JWT 校验所需的公钥集 URL
`audience`	`str / list[str] / None`	`None`	允许的令牌受众；未设置时不限制受众
`allowed_algorithms`	`list[str]`	`["RS256"]`	允许的 JWT 签名算法
`jwks_cache_ttl_seconds`	`int`	`300`	公钥集缓存时间，单位为秒
`jwks_kid_miss_cooldown_seconds`	`int`	`30`	未命中密钥标识时再次刷新公钥集的最短间隔，单位为秒
`use_introspection`	`bool`	`False`	改用提供商的令牌内省端点验证访问令牌
`introspection_url`	`str / None`	`None`	启用令牌内省时必填的端点 URL
`introspection_client_id`	`str / None`	`None`	内省认证客户端 ID；仅与内省密钥同时设置时生效，否则使用原客户端凭据
`introspection_client_secret`	`str / None`	`None`	内省认证密钥；仅与内省客户端 ID 同时设置时生效，否则使用原客户端凭据
`introspection_cache_ttl_seconds`	`int`	`300`	内省结果缓存时间上限，单位为秒；同时受令牌到期时间限制
`introspection_cache_max_entries`	`int`	`1000`	内省缓存条目上限

存储与请求行为

参数	类型	默认值	说明
`state_ttl_seconds`	`int`	`300`	默认内存 state 存储的有效期，单位为秒
`state_max_entries`	`int`	`10000`	默认内存 state 存储的条目上限
`http_timeout_seconds`	`float`	`30.0`	OAuth2 HTTP 请求超时，单位为秒
`http_max_connections`	`int`	`100`	OAuth2 HTTP 客户端最大连接数
`http_max_keepalive_connections`	`int`	`20`	OAuth2 HTTP 客户端最大保活连接数
`api_path_prefixes`	`list[str]`	`["/api/"]`	未登录时返回 401 而非登录重定向的 API 路径前缀

从用户信息端点获取的信息仅保留适合写入浏览器会话 Cookie 的标准字段：sub、email、email_verified、name、given_name、family_name、preferred_username、picture、locale、updated_at，以及通过 user_id_field 配置的用户标识字段。仅保留类型为字符串、整数、浮点数或布尔值的字段值，以避免会话 Cookie 超出浏览器大小限制。/oauth2/userinfo 端点返回的即为这些过滤后的字段。

多进程共享 OAuth state

默认的 InMemoryStateStore 仅适用于单进程。多实例应用需要所有实例共享同一 state 存储，并保证 state 只能使用一次以下为替代 setup_oauth2() 调用的配置片段，复用前文的 app 与 config。先安装 redis 包，准备支持 GETDEL 的 Redis 6.2 及以上版本，并设置 REDIS_URL。应用使用独立键前缀，所有实例保持一致；生产连接与凭据按部署要求配置

import json
import os
import secrets

from redis import Redis

class RedisStateStore:
    def __init__(self, client, ttl_seconds=300):
        self.client = client
        self.ttl_seconds = ttl_seconds
        self.prefix = "oauth2:my-app:"

    def create_state(self, redirect_after_auth="/", code_verifier=None):
        state = secrets.token_urlsafe(32)
        data = json.dumps({
            "redirect_after_auth": redirect_after_auth,
            "code_verifier": code_verifier,
        })
        self.client.setex(self.prefix + state, self.ttl_seconds, data)
        return state

    def validate_and_consume_state(self, state):
        data = self.client.getdel(self.prefix + state)
        return json.loads(data) if data else None

redis_client = Redis.from_url(os.environ["REDIS_URL"], decode_responses=True)
setup_oauth2(
    app,
    config,
    state_store=RedisStateStore(redis_client, ttl_seconds=config.state_ttl_seconds),
)

create_state() 返回随机 state 并保存重定向地址与 PKCE 校验值；validate_and_consume_state() 原子读取并删除记录，失效时返回 None。自定义存储自行管理有效期、容量与连接生命周期，state_max_entries 不会自动限制 Redis 中的记录

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 回退，避免把业务错误或服务故障误判为身份令牌失效。

托管 API Key 凭据鉴权

当下游 AgentCard 在 capabilities.extensions 中声明了凭据提供方（包含 credentialProviderName 与 poolName），且 security / securitySchemes 未产生有效的认证头时，VeADK 会向身份服务查询该凭据提供方托管的 API Key，并按照返回的凭据元信息中指定的请求头名称与前缀构造认证头。此机制由 Agent Identity 统一托管 API Key，无需在 VeADK 侧手动配置。

VeADK 支持解析 A2A 1.0 AgentCard：当 AgentCard 未提供顶层 url 字段时，会从 supportedInterfaces 中按协议绑定类型和版本解析调用地址，优先选择 JSONRPC 绑定与 1.0 协议版本。

技能沙箱中的身份透传

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

会话与部署限制

cookie_signing_secret 用于签名浏览器会话，省略时回退到 client_secret；公开客户端应显式配置稳定的签名密钥。签名用于防篡改，不等于加密。多实例部署需共享签名密钥和 OAuth state 存储，且公网回调必须与客户端登记地址完全一致

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

API Key 认证

OAuth2 单点登录

API 网关模式

Starlette / FastAPI 中间件

应用集成参数

VeIdentity 配置参数

OAuth2Config 参数

端点与授权请求

访问令牌校验

存储与请求行为

多进程共享 OAuth state

OAuth2 JWT 认证

A2A 调用中的身份透传

托管 API Key 凭据鉴权

技能沙箱中的身份透传

会话与部署限制

​API Key 认证

​OAuth2 单点登录

​API 网关模式

​Starlette / FastAPI 中间件

​应用集成参数

​VeIdentity 配置参数

​OAuth2Config 参数

​端点与授权请求

​会话与 Cookie

​访问令牌校验

​存储与请求行为

​多进程共享 OAuth state

​OAuth2 JWT 认证

​A2A 调用中的身份透传

​托管 API Key 凭据鉴权

​技能沙箱中的身份透传

​会话与部署限制

API Key 认证

OAuth2 单点登录

API 网关模式

Starlette / FastAPI 中间件

应用集成参数

VeIdentity 配置参数

OAuth2Config 参数

端点与授权请求

会话与 Cookie

访问令牌校验

存储与请求行为

多进程共享 OAuth state

OAuth2 JWT 认证

A2A 调用中的身份透传

托管 API Key 凭据鉴权

技能沙箱中的身份透传

会话与部署限制