feat(identity): add tutorial-1-userpool-inbound and tutorial-2-feishu…

01-tutorials/identity/README.md

@@ -0,0 +1,108 @@
+# Agent Identity 入门教程
+
+> 为智能体提供企业级身份与权限管理能力
+
+## 概述
+
+随着 LLM 应用的爆发，我们注意到一个明显的趋势：开发者使用 veADK/LangChain 等框架在本地（VS Code/Cursor）构建一个 Demo 非常容易。但在将智能体推向**企业级生产环境**时，往往会撞上一堵“安全墙”。
+
+与传统的微服务不同，真正的企业级 Agent 必须具备 **自主行动能力（Agency）**。而受制于模型能力，Agent 的行为又是不可预测的。这带来了三个核心挑战：
+
+
+
+
+1.  **入站安全 (Inbound Security) —— 谁能调用 Agent？**
+    * 常见的基于 API Key 的访问方式由于缺乏防重放机制，安全性低。
+    * 企业往往希望复用既有 IdP ，Agent 需要支持通过 SSO (如飞书) 方式验证用户身份，确保只有授权用户才能发起对话。
+
+2.  **出站安全 (Outbound Security) —— Agent 代表谁在操作？**
+    * **凭证泄露风险**：开发者习惯将 API Key 硬编码在 Agent 代码中，这是巨大的安全隐患。
+    * **权限越界**：当 Agent 访问飞书文档或数据库时，它应该拥有“上帝视角”，还是仅拥有“当前用户”的权限？
+    * **身份传递**：如何让后端资源知道，这次调用是由“User A”授权“Agent B”发起的？
+
+3.  **细粒度权限管控 (Governance) —— 如何管控“黑盒”？**
+    * Agent 需要细粒度的策略控制，而不是一把梭的 `Admin` 权限。
+    * 企业 CISO 和安全团队需要知道 Agent 到底访问了什么资源，以便
+
+## Agent Identity 解决方案
+
+Agent Identity 专为解决上述问题设计，它不是简单的 OAuth 包装，而是为智能体构建的一套完整的**身份治理基础设施**。
+
+![](2026-01-09-15-52-39.png)
+
+Agent Identity 把“用户 → 应用 → Agent → 资源”的链路拆开治理，并提供一套可复用的安全构件：
+
+- **Inbound 认证**：对接企业现有 IdP（用户池 / OAuth / SSO 等），让“谁能调用 Agent”可配置、可审计。
+- **Agent 权威身份**：为 Agent 提供唯一、可验证的身份主体，便于策略绑定与审计归因。
+- **Outbound 凭证托管（Token Vault）**：把 OAuth / API Key 的存储、刷新、最小化授权从业务代码中剥离出来；默认做到“凭据不落地”。
+- **细粒度权限控制**：基于委托链（Delegation Chain）把“用户权限”和“Agent 权限”组合校验，默认拒绝、按需放开。
+- **可观测与审计**：把“谁在什么时候代表谁调用了哪个工具/资源”沉淀为审计事件，方便排障、合规与内控。
+
+## 实验列表
+| 实验 | 说明 | 目录 |
+|------|------|------|
+| **实验1: 用户池认证** | 使用用户池管控智能体访问 (Inbound 认证) | [tutorial-1-userpool-inbound](./tutorial-1-userpool-inbound/) |
+| **实验2: 飞书联合登录** | 使用飞书账号作为企业身份源 (IdP 集成) | [tutorial-2-feishu-idp](./tutorial-2-feishu-idp/) |
+
+## 核心功能
+
+- **身份认证 (Inbound)**: 验证用户身份，只有授权用户才能访问 Agent
+- **凭证托管 (Outbound)**: Agent 安全访问飞书等外部服务，凭证由平台管理
+- **权限控制**: 基于委托链的细粒度权限，控制 Agent 能访问的资源
+
+
+## 目录结构说明
+
+```
+identity/
+├── README.md                           # 本文件
+├── tutorial-1-userpool-inbound/        # 实验1: Inbound 认证
+│   ├── README.md                       # 教程文档
+│   ├── main.py                         # 示例代码
+│   ├── pyproject.toml                  # 依赖配置
+│   ├── .env.template                   # 环境变量模板
+│   └── assets/                         # 截图和流程图
+└── tutorial-2-feishu-idp/              # 实验2: 飞书 IdP 联合登录
+    ├── README.md
+    ├── main.py
+    ├── pyproject.toml
+    ├── .env.template
+    └── assets/
+```
+
+## 本地运行
+
+### 前置准备
+
+| 项目 | 说明 |
+|------|------|
+| **火山控制台账号** | 需要 IDFullAccess、STSAssumeRoleAccess 权限的子账号 |
+| **Python 环境** | Python 3.12+ 及 [uv](https://docs.astral.sh/uv/) |
+| **飞书账号**（实验2/3） | 用于测试飞书登录和文档访问 |
+
+### 快速开始
+
+```bash
+# 1. 克隆仓库
+git clone https://github.com/volcengine/agentkit-samples.git
+cd agentkit-samples/01-tutorials/identity
+
+# 2. 选择实验目录
+cd tutorial-1-userpool-inbound  # 或其他实验
+
+# 3. 配置环境变量
+cp .env.template .env
+# 编辑 .env 填写配置
+
+# 4. 安装依赖
+uv sync
+
+# 5. 启动服务
+uv run veadk web
+```
+
+## AgentKit 部署
+
+本教程所有示例均可通过 `uv run veadk web` 在本地运行。
+
+如需部署到 AgentKit Runtime，请参考 [AgentKit Runtime 文档](https://volcengine.github.io/agentkit-sdk-python/content/4.runtime/1.runtime_quickstart.html)。

01-tutorials/identity/tutorial-1-userpool-inbound/.env.example

@@ -0,0 +1,16 @@
+# ==================== 用户池认证配置 ====================
+# 从 Agent Identity 控制台获取
+# https://console.volcengine.com/identity/region:identity+cn-beijing/user-pools
+
+ADK_OAUTH2_USERPOOL_UID=        # 用户池 UID（用户池详情页可见）
+ADK_OAUTH2_CLIENT_ID=           # OAuth2 客户端 ID
+ADK_OAUTH2_CLIENT_SECRET=       # OAuth2 客户端 Secret
+ADK_OAUTH2_CALLBACK_URL=http://127.0.0.1:8000/api/v1/oauth2callback
+ADK_OAUTH2_SCOPE="openid profile"
+
+# ==================== 火山云凭证 ====================
+# 从火山引擎控制台获取
+# https://console.volcengine.com/iam/keymanage
+
+VOLCENGINE_ACCESS_KEY=          # 子账号 Access Key
+VOLCENGINE_SECRET_KEY=          # 子账号 Secret Key

01-tutorials/identity/tutorial-1-userpool-inbound/README.md

@@ -0,0 +1,201 @@
+# 实验1: 使用用户池管控智能体访问
+
+> 10 分钟内为您的智能体配置企业级访问控制
+
+## 为什么需要 Inbound 认证？
+
+### 先想一个问题
+
+你写了一个 Agent，本地跑得很好。现在要上线给用户用了。
+
+这时候你会遇到一个最基本的问题：**谁能调用你的 Agent？**
+
+### 没有认证会怎样？
+
+**场景 1：裸奔的 Agent**
+
+```
+互联网 ──────► 你的 Agent ──────► 模型 API（按 Token 计费）
+  │
+  └── 任何人都能调用
+```
+
+后果：
+- 有人写个脚本疯狂调用，你的 API 费用一夜爆炸
+- 竞争对手拿你的 Agent 做逆向工程
+- 出了安全事故，你不知道是谁干的
+
+**场景 2：Agent 不知道"你是谁"**
+
+很多 Agent 需要根据用户身份提供个性化服务：
+- 查"我的订单" —— 哪个"我"？
+- 访问"我的文档" —— 哪个"我"？
+- 执行敏感操作 —— 你有权限吗？
+
+没有身份信息，Agent 要么拒绝服务，要么只能提供最基础的公开功能。
+
+**场景 3：审计和合规**
+
+安全团队、CISO 会问你：
+- 这个 Agent 谁在用？
+- 用了多少次？
+- 有没有异常调用？
+
+你答不上来，合规审计直接挂掉。金融、医疗、政企客户根本不会用。
+
+### 核心问题：入站身份
+
+把链路画出来就很清楚：
+
+```
+用户 ──► 应用 ──► Agent ──► 资源
+     │
+     └── 这里需要回答：你是谁？你有权限吗？
+```
+
+这就是 **Inbound（入站）认证** 要解决的事：
+1. **认证**：证明"你是你"
+2. **授权**：确认"你能用"
+3. **传递**：把身份信息带给 Agent
+
+### Agent Identity 怎么解决？
+
+我们提供开箱即用的 **用户池** 方案：
+
+| 能力 | 说明 |
+|------|------|
+| **统一用户目录** | 一个地方管理所有能访问 Agent 的用户 |
+| **标准协议** | OAuth2/OIDC，不用自己造轮子 |
+| **JWT Token** | 无状态认证，高性能，身份信息可传递给 Agent |
+| **企业级安全** | 支持 MFA、密码策略、登录审计 |
+
+配置完成后，调用链路变成：
+
+```
+用户 ──► 登录（用户池）──► 拿到 Token ──► 带 Token 调用 Agent
+                                              │
+                                              ▼
+                                        Agent 验证 Token
+                                        知道是谁在调用
+                                        记录审计日志
+```
+
+**10 分钟配置，解决三个问题：谁能用、谁在用、用了什么。**
+
+---
+
+## 快速开始
+
+### 步骤1: 创建用户池和用户（控制台操作）
+
+1. **访问 Agent Identity 控制台**
+
+   打开 [用户池管理页面](https://console.volcengine.com/identity/region:identity+cn-beijing/user-pools)
+
+2. **新建用户池**
+   - 点击「创建用户池」
+   - 填写用户池名称（如 `my_agent_users`）
+   - 选择登录属性：用户名 + 手机号
+   - 点击「确认」
+![alt text](image-2.png)
+3. **新建客户端**
+   - 进入用户池详情 → 点击「新建客户端」
+   - 客户端名称：`agent_web_client`
+   - 客户端类型：Web 应用
+   - 回调地址：`http://127.0.0.1:8000/api/v1/oauth2callback`
+   - **记录 Client ID 和 Client Secret**
+![alt text](image-3.png)
+4. **创建测试用户**
+   - 在用户池中选择「用户管理」→「新建用户」
+   - 设置用户名和临时密码
+![alt text](image-4.png)
+
+### 步骤2: 配置环境变量
+
+复制环境变量模板并填写：
+
+```bash
+cp .env.template .env
+```
+
+编辑 `.env` 文件：
+
+```bash
+# 用户池配置（从控制台复制）
+ADK_OAUTH2_USERPOOL_UID=your-userpool-uid
+ADK_OAUTH2_CLIENT_ID=your-client-id
+ADK_OAUTH2_CLIENT_SECRET=your-client-secret
+ADK_OAUTH2_CALLBACK_URL=http://127.0.0.1:8000/api/v1/oauth2callback
+ADK_OAUTH2_SCOPE="openid profile"
+
+# 火山云凭证
+VOLCENGINE_ACCESS_KEY=your-access-key
+VOLCENGINE_SECRET_KEY=your-secret-key
+```
+
+### 步骤3: 启动 Agent 应用
+
+```bash
+# 安装依赖（首次运行）
+uv sync
+
+# 启动服务
+uv run veadk web
+```
+
+服务启动后，访问 http://127.0.0.1:8000
+
+### 步骤4: 用户登录体验
+
+1. **访问应用** - 浏览器打开 http://127.0.0.1:8000
+2. **跳转登录** - 自动跳转到用户池登录页面
+3. **输入凭证** - 使用步骤1创建的用户登录
+4. **首次修改密码** - 如有要求，设置新密码
+5. **授权确认** - 允许应用访问您的信息
+6. **进入应用** - 登录成功，可以开始使用 Agent
+![alt text](image-5.png)
+![alt text](image-6.png)
+```
+未授权访问 → 401 Unauthorized
+授权访问   → 正常响应
+```
+
+---
+
+## 核心能力回顾
+>
+> "通过 Agent Identity，您可以在 **10 分钟内**为智能体配置企业级访问控制，
+> 确保只有授权用户才能使用 Agent 服务。
+>
+> - **安全合规**：满足金融、医疗等行业的身份认证要求
+> - **统一管理**：集中管理用户，支持 MFA 二次验证
+> - **无缝集成**：标准 OAuth2 协议，易于与现有系统对接
+> - **审计追溯**：每次访问都有记录，满足审计需求"
+
+
+## 进阶: 与飞书/企业 IdP 集成
+
+想让用户使用飞书账号登录？请参考：
+
+→ [实验2: 飞书 IdP 联合登录](../tutorial-2-feishu-idp/README.md)
+
+想让 Agent 安全访问飞书文档？请参考：
+
+→ [实验3: 让智能体安全访问飞书文档](../tutorial-3-feishu-outbound/README.md)
+
+---
+
+## 常见问题
+
+| 问题 | 解决方案 |
+|------|----------|
+| 登录页面一直跳转 | 清除浏览器缓存，检查回调地址配置 |
+| Token 过期 | 默认 10 小时有效，可配置刷新机制 |
+| 忘记 Client Secret | 在控制台重新生成 |
+
+---
+
+## 相关资源
+
+- [Agent Identity 产品文档](https://www.volcengine.com/docs/identity)
+- [VeADK 开发指南](https://volcengine.github.io/agentkit-sdk-python/)