Skip to content

Commit 4e81f59

Browse files
loveyanaloveyana
committed
feat(ve_identity): Add Agent Identity authentication docs
Introduces documentation for Agent Identity authentication, including product overview, API Key outbound, OAuth2 M2M outbound, and OAuth2 USER_FEDERATION outbound.
1 parent 3561379 commit 4e81f59

File tree

5 files changed

+496
-0
lines changed

5 files changed

+496
-0
lines changed

‎docs/content/91.auth/.navigation.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
title: 认证与授权

‎docs/content/91.auth/1.agent-identity-intro.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
title: Agent Identity 产品介绍
3+
description: Agent Identity 身份认证产品的开通流程和作用
4+
navigation:
5+
icon: i-lucide-shield-check
6+
---
7+
8+
Agent Identity 是火山引擎提供的一站式身份及权限管理平台，负责用户身份验证、权限控制，确保 Agent 出、入操作的安全性与合规性。
9+
10+
## 核心功能
11+
12+
- **用户身份管理**：支持用户池管理、企业 IdP（SAML/OIDC）及第三方身份联合
13+
- **工作负载身份管理**：为 Agent/工具分配唯一数字身份，维护属性标签
14+
- **第三方凭据托管**：加密托管 API Key 和 OAuth 令牌，杜绝明文凭据泄露
15+
- **权限管控**：基于属性和上下文的动态授权，实现细粒度权限控制
16+
17+
## 开通流程
18+
19+
### 1. 访问 Agent Identity 控制台
20+
21+
访问 **[Agent Identity](https://console.volcengine.com/identity)** 服务开通页，勾选 **同意服务条款**, 点击 **开通并授权**。
22+
23+
### 2. 创建出站凭据提供商
24+
25+
根据使用场景创建相应的出站凭据提供商：
26+
27+
| 认证方式 | 提供商类型 | 使用场景 |
28+
|---------|----------|--------|
29+
| API Key | API Key | 服务间通信 |
30+
| OAuth2 M2M | OAuth Client | 后端服务间认证 |
31+
| OAuth2 USER_FEDERATION | OAuth Client | 用户委托认证 |
32+
33+
### 3. 配置凭证信息
34+
35+
根据认证方式配置相应的凭证（如 API Key、Client ID、Client Secret、回调 URL 等）。
36+
37+
### 4. 快速使用
38+
39+
```python
40+
from veadk.integrations.ve_identity import (
41+
VeIdentityFunctionTool,
42+
api_key_auth,
43+
)
44+
45+
auth_config = api_key_auth(provider_name="my-provider")
46+
tool = VeIdentityFunctionTool(
47+
func=my_function,
48+
auth_config=auth_config,
49+
into="api_key",
50+
)
51+
```
52+
53+
## 常见问题
54+
55+
**Q: 如何选择认证方式？**
56+
57+
A:
58+
- **API Key**：简单、固定凭证，适合简单场景
59+
- **OAuth2 M2M**：安全、支持令牌过期和刷新，适合生产环境
60+
- **OAuth2 USER_FEDERATION**：用户授权，适合需要用户同意的场景
61+
62+
**Q: 凭证会被暴露吗？**
63+
64+
A: 不会。Agent Identity 会：
65+
- 加密存储凭证
66+
- 支持凭证自动轮换
67+
- 不在代码中暴露凭证
68+
69+
**Q: 如何处理凭证过期？**
70+
71+
A: Agent Identity 会自动处理：
72+
- 令牌缓存和刷新
73+
- 凭证自动轮换
74+
- 过期前自动更新
75+
76+
## 后续步骤
77+
78+
- [使用 API Key 进行出站认证](./2.api-key-outbound.md)
79+
- [使用 OAuth2 M2M 进行出站认证](./3.oauth2-m2m-outbound.md)
80+
- [使用 OAuth2 USER_FEDERATION 进行出站认证](./4.oauth2-user-federation-outbound.md)
81+
82+
## 相关资源
83+
84+
### Agent Identity 官方文档
85+
- [Agent Identity API 参考](https://www.volcengine.com/docs/6758/1261038)
86+
87+
### 外部资源
88+
- [OAuth2 规范](https://tools.ietf.org/html/rfc6749)
89+
- [OpenID Connect](https://openid.net/connect/)
90+
91+
## 获取帮助
92+
93+
如有问题，请：
94+
1. 查看相应文档的常见问题部分
95+
2. 查看 [Agent Identity 官方文档](https://www.volcengine.com/docs/6758/1261038)
96+
3. 联系火山引擎技术支持

‎docs/content/91.auth/2.api-key-outbound.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
title: 使用 API Key 进行出站认证
3+
description: 通过 API Key 认证访问外部服务
4+
navigation:
5+
icon: i-lucide-key
6+
---
7+
8+
API Key 认证是最简单的出站认证方式，适用于服务间通信和固定凭证场景。
9+
10+
## 创建 API Key 凭据
11+
12+
1. 登录火山引擎控制台，导航到 **Agent Identity** 服务
13+
2. 在左侧导航树中，选择 **身份认证 > 出站凭据托管**
14+
3. 点击 **新建 > 新建 API Key**，填写 API Key 名称
15+
4. 输入第三方服务提供的 API Key
16+
5. 配置 API Key 传递方式（Header 或 Query）并点击 **确定**
17+
18+
## 使用方式
19+
20+
### VeIdentityFunctionTool
21+
22+
```python
23+
from veadk.integrations.ve_identity import VeIdentityFunctionTool, api_key_auth
24+
import aiohttp
25+
26+
async def call_api(api_key: str, endpoint: str):
27+
headers = {"Authorization": f"Bearer {api_key}"}
28+
async with aiohttp.ClientSession() as session:
29+
async with session.get(endpoint, headers=headers) as resp:
30+
return await resp.json()
31+
32+
auth_config = api_key_auth(provider_name="my-api-provider")
33+
tool = VeIdentityFunctionTool(
34+
func=call_api,
35+
auth_config=auth_config,
36+
into="api_key",
37+
)
38+
```
39+
40+
### VeIdentityMcpToolset
41+
42+
```python
43+
from veadk.integrations.ve_identity import VeIdentityMcpToolset, api_key_auth
44+
from google.adk.agents.mcp import StdioServerParameters
45+
46+
auth_config = api_key_auth(provider_name="my-api-provider")
47+
toolset = VeIdentityMcpToolset(
48+
auth_config=auth_config,
49+
connection_params=StdioServerParameters(
50+
command="python",
51+
args=["-m", "my_api_mcp_server"],
52+
),
53+
)
54+
```
55+
56+
## 环境变量配置
57+
58+
```bash
59+
export VOLCENGINE_ACCESS_KEY="your-access-key-id"
60+
export VOLCENGINE_SECRET_KEY="your-secret-access-key"
61+
export VOLCENGINE_SESSION_TOKEN="your-session-token" # 可选
62+
```
63+
64+
在 VeFaaS 环境中，Agent Identity 会自动从 `/var/run/secrets/iam/credential` 读取凭证。
65+
66+
## 示例
67+
68+
```python
69+
import asyncio
70+
from veadk import Agent, Runner
71+
from veadk.integrations.ve_identity import VeIdentityFunctionTool, api_key_auth
72+
import aiohttp
73+
74+
async def query_api(api_key: str, user_id: str):
75+
headers = {"Authorization": f"Bearer {api_key}"}
76+
url = f"https://api.example.com/users/{user_id}"
77+
async with aiohttp.ClientSession() as session:
78+
async with session.get(url, headers=headers) as resp:
79+
return await resp.json()
80+
81+
tool = VeIdentityFunctionTool(
82+
func=query_api,
83+
auth_config=api_key_auth(provider_name="user-api"),
84+
into="api_key",
85+
)
86+
87+
agent = Agent(tools=[tool])
88+
runner = Runner(agent=agent)
89+
asyncio.run(runner.run(messages="查询用户 123"))
90+
```
91+
92+
## 常见问题
93+
94+
**Q: 如何更新 API Key？**
95+
96+
A: 在 Agent Identity 控制台中编辑凭证即可。
97+
98+
**Q: 如何处理 API 调用失败？**
99+
100+
A: 实现错误处理和重试逻辑。
101+
102+
## 相关资源
103+
104+
- [Agent Identity 产品介绍](./1.agent-identity-intro.md)
105+
- [OAuth2 M2M 认证](./3.oauth2-m2m-outbound.md)
106+
- [OAuth2 USER_FEDERATION 认证](./4.oauth2-user-federation-outbound.md)
107+
- [Agent Identity API 参考](https://www.volcengine.com/docs/6758/1261038)
108+

‎docs/content/91.auth/3.oauth2-m2m-outbound.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
title: 使用 OAuth2 M2M 进行出站认证
3+
description: 通过 OAuth2 M2M 认证进行机器对机器通信
4+
navigation:
5+
icon: i-lucide-network
6+
---
7+
8+
OAuth2 M2M（Machine to Machine）认证用于服务间通信，比 API Key 更安全且支持令牌刷新。
9+
10+
## 创建 OAuth2 M2M 凭据
11+
12+
### 基础步骤
13+
14+
1. 登录火山引擎控制台，导航到 **Agent Identity** 服务
15+
2. 在左侧导航树中，选择 **身份认证 > 出站凭据托管 > OAuth Client**
16+
3. 点击 **新建 > 新建 OAuth Client**
17+
4. 在 **OAuth2 流程** 中选择 **机器对机器（M2M）**
18+
5. 点击 **确定** 完成创建
19+
20+
### 方式一：使用内置 Vendor（推荐）
21+
22+
选择提供商类型：**Google**、**GitHub** 或 **Coze**，填写：
23+
- Client ID
24+
- Client Secret
25+
26+
### 方式二：使用 OIDC 配置
27+
28+
选择提供商类型为 **自定义**，填写：
29+
- 发行者 URL：OIDC 提供商的 Discovery URL（如 `https://accounts.google.com/.well-known/openid-configuration`）
30+
- Client ID
31+
- Client Secret
32+
- 权限范围：至少包含 `openid`
33+
34+
### 方式三：使用自定义 OAuth2 配置
35+
36+
选择提供商类型为 **自定义**，填写：
37+
- Client ID
38+
- Client Secret
39+
- 权限范围
40+
- Issuer
41+
- 授权端点
42+
- 令牌端点
43+
44+
## 使用方式
45+
46+
### VeIdentityFunctionTool
47+
48+
```python
49+
from veadk.integrations.ve_identity import VeIdentityFunctionTool, oauth2_auth
50+
import aiohttp
51+
52+
async def call_service(access_token: str, endpoint: str):
53+
headers = {"Authorization": f"Bearer {access_token}"}
54+
async with aiohttp.ClientSession() as session:
55+
async with session.get(endpoint, headers=headers) as resp:
56+
return await resp.json()
57+
58+
auth_config = oauth2_auth(
59+
provider_name="my-oauth2-m2m-provider",
60+
scopes=["api://your-service/.default"],
61+
auth_flow="M2M",
62+
)
63+
tool = VeIdentityFunctionTool(
64+
func=call_service,
65+
auth_config=auth_config,
66+
)
67+
```
68+
69+
### VeIdentityMcpToolset
70+
71+
```python
72+
from veadk.integrations.ve_identity import VeIdentityMcpToolset, oauth2_auth
73+
from google.adk.agents.mcp import StdioServerParameters
74+
75+
auth_config = oauth2_auth(
76+
provider_name="my-oauth2-m2m-provider",
77+
scopes=["api://your-service/.default"],
78+
auth_flow="M2M",
79+
)
80+
toolset = VeIdentityMcpToolset(
81+
auth_config=auth_config,
82+
connection_params=StdioServerParameters(
83+
command="python",
84+
args=["-m", "my_service_mcp_server"],
85+
),
86+
)
87+
```
88+
89+
## 常见问题
90+
91+
**Q: OAuth2 M2M 和 API Key 有什么区别？**
92+
93+
A: API Key 简单固定，OAuth2 M2M 更安全且支持令牌刷新。
94+
95+
**Q: 令牌过期了怎么办？**
96+
97+
A: Agent Identity 会自动刷新令牌。
98+
99+
**Q: 如何配置多个 Scopes？**
100+
101+
A:
102+
```python
103+
auth_config = oauth2_auth(
104+
provider_name="my-provider",
105+
scopes=["api://service1/.default", "api://service2/.default"],
106+
auth_flow="M2M",
107+
)
108+
```
109+
110+
## 相关资源
111+
112+
- [Agent Identity 产品介绍](./1.agent-identity-intro.md)
113+
- [API Key 认证](./2.api-key-outbound.md)
114+
- [OAuth2 USER_FEDERATION 认证](./4.oauth2-user-federation-outbound.md)
115+
- [Agent Identity API 参考](https://www.volcengine.com/docs/6758/1261038)
116+

0 commit comments

Comments
 (0)