入站认证

入站认证控制谁能调用你的智能体——它是安全概述四个平面之一。VeADK 支持两种方式：API Key（简单，适合 A2A/MCP Server）与 OAuth2（推荐，支持单点登录）。本页介绍两者的接入方式。出站方向（智能体调用外部服务）见出站认证。

API Key 认证

VeADK 将 API Key 通过 URL 的 token 查询参数传递，由 API 网关校验。

API Key 仅适用于 A2A/MCP Server 部署模式。VeADK Web 部署模式更推荐 OAuth2。

创建 Agent 时指定 API Key 认证，或在部署已有项目时加上 --auth-method=api-key。用户访问时，API 网关校验 token 参数中的 API Key。

OAuth2 单点登录

OAuth2 用令牌代替账号密码授予有限访问，一次登录即可访问多个关联应用。VeADK 提供两种接入方式：

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

方式一：API 网关模式（VeFaaS 部署）

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

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

创建 Agent 时指定 OAuth2 认证，或在部署时加上 --auth-method=oauth2，VeADK 会自动创建 Identity 用户池和客户端。复用已有资源时，用 --user-pool-name 和 --client-name 指定。

部署后在 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()  # 换成 Starlette() 即可用于纯 Starlette 应用

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

from_veidentity() 会自动创建用户池与客户端（如不存在）、注册回调 URL、配置 OAuth2 端点。中间件注册的路由：

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

中间件会区分请求类型：浏览器请求重定向到登录页；API 请求返回 401 Unauthorized JSON。API 请求通过 Accept: application/json、路径前缀（默认 /api/）或 X-Requested-With: XMLHttpRequest 识别。

常用配置

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 开发需禁用安全 cookie
        auto_create=False,             # 复用已有资源，不存在时报错
        auto_register_callback=False,  # 不修改回调 URL
        api_path_prefixes=["/api/", "/graphql"],
    ),
    exempt_paths=["/health", "/metrics"],      # 跳过认证：精确匹配
    exempt_prefixes=["/public/", "/static/"],  # 跳过认证：前缀匹配
)

接入非 VeIdentity 的 OAuth2 提供商时，直接构造 OAuth2Config(authorize_url=..., token_url=..., userinfo_url=..., client_id=..., client_secret=..., redirect_uri=...)。

OAuth2Config.from_veidentity() 的关键参数：user_pool_name、client_name、redirect_uri（必填），auto_create（默认 True）、auto_register_callback（默认 True）、client_type（默认 WEB_APPLICATION）、scope（默认 "openid profile email"）。OAuth2Config 还支持 session_timeout_seconds（默认 3600）、cookie_secure（默认 True）、auto_refresh_token（默认 True）、token_refresh_threshold_seconds（默认 300）等。

分布式部署

默认的 InMemoryStateStore 仅适用于单进程。分布式场景需用 Redis 等外部存储——实现 create_state / validate_and_consume_state 两个方法即可，例如：

import json
import secrets


class RedisStateStore:
    def __init__(self, redis_client, ttl: int = 300):
        self._redis = redis_client
        self._ttl = ttl

    def create_state(self, redirect_after_auth: str = "/", code_verifier=None) -> str:
        state = secrets.token_urlsafe(32)
        self._redis.setex(
            f"oauth2:{state}",
            self._ttl,
            json.dumps({
                "redirect_after_auth": redirect_after_auth,
                "code_verifier": code_verifier,
            }),
        )
        return state

    def validate_and_consume_state(self, state: str):
        key = f"oauth2:{state}"
        data = self._redis.get(key)
        if not data:
            return None
        self._redis.delete(key)
        return json.loads(data)


setup_oauth2(app, config, state_store=RedisStateStore(redis_client))

OAuth2 JWT 认证

A2A/MCP Server 支持用 JWT 承载 OAuth2 授权令牌。创建 Agent 时指定 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 请求头中取得令牌。