Sts Entraid Single A2a Adkagent MCP Poc

MCPAI代理

提供方 sanjay-sts

AI代理 stdio · 本地进程 OAuth 授权 社区 / 第三方 Claude
查看接入方式

一个安全的多层AI代理系统,用户身份从前端认证传播到代理层再到资源API,通过三层独立访问控制实现深度防御。

一句话选型结论

按资料字段整理

Sts Entraid Single A2a Adkagent MCP Poc 属于AI代理类 MCP 服务器,stdio · 本地进程,OAuth 授权,可直接接入 Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式stdio · 本地进程 鉴权OAuth 授权 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 7 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量7暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

AI代理本地部署身份认证访问控制OAuth2.0RBAC

安装与配置

stdio · 本地进程 OAuth 授权
客户端在本机拉起子进程,数据不出本机
pip install -r requirements.txt

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 7 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 7 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好OAuth 授权对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Sts Entraid Single A2a Adkagent MCP Poc当前 7 stdio · 本地进程 本地部署 有 2026-05-17
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方sanjay-sts上游标注的维护方 sanjay-sts
分类AI代理本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式OAuth 授权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

41.6 KB
来自项目仓库与上游目录的原文,未做删改

身份感知人工智能代理系统

一个安全的多层人工智能代理系统,用户身份从前端身份验证通过代理层传播到资源API。该架构在三个独立的级别上实施访问控制,提供深度防御。

目录

  • 系统设计
  • 当前状态
  • 架构图
  • 身份验证流程
  • 多回合对话流程
  • 上下文和身份传递
  • RBAC(基于角色的访问控制)
  • API 参考
  • 安装指南
  • 测试

系统设计

概述

该系统使用 OAuth 2.0与OpenID连接(OIDC) 对于身份验证和授权,支持多个身份提供商(Microsoft Entra ID和AWS Cognito):

  • 协议:使用PKCE(代码交换证明密钥)的OAuth 2.0授权代码流
  • 令牌格式:由IdP签名的JWT访问令牌,通过JWKS(JSON Web密钥集)验证
  • 前端:使用MSAL.js 3.6(Entra)+AWS Amplify 6(Cognito)进行反应——统一的身份验证提供者
  • 网关:A2A用于代理发现和请求路由的协议服务器
  • 代理:谷歌ADK与克劳德·海库4.5通过LiteLLM(AWS基岩)
  • 工具:提供身份识别软件工具的FastMCP服务器(Graph API+S3)

技术栈

组件 技术 端口 目的
前端 React 18+MSAL.js 3.6+AWS Amplify 6 10003 用户身份验证、令牌获取
网关 A2A协议(FastAPI+A2A-sdk) 10000 代理发现、代理级ACL、流媒体
代理 谷歌ADK+LiteLLM+Claude Haiku 4.5(基岩) 10001 LLM编排、工具调用
工具 FastMCP(无状态HTTP) 10002 工具执行、令牌传播
身份 Entra ID+AWS Cognito - OAuth 2.0+OIDC,多IdP JWT验证
资源 Microsoft Graph API、AWS S3 - 用户数据、文件、电子邮件、云存储

三层安全模型

级别 位置 机制 强制执行 拒绝访问
1.代理人 A2A服务器 组成员资格,阻止列表 auth_middleware 用户被阻止或不在允许的组中
2.工具 FastMCP 基于角色的权限(RBAC) 内置身份验证(JWT验证)+ auth=require_role() 装饰师+ UserContextMiddleware 令牌无效、未担任角色或角色缺乏工具权限
3.资源 Graph API OAuth作用域 Microsoft Graph 缺少所需作用域的令牌

当前状态

工作特点

功能 状态 注释
入境者身份验证 ✅ 工作中 MSAL.js弹出/静默令牌获取
AWS Cognito身份验证 ✅ 工作 增强托管UI重定向流
自定义API范围 ✅ 工作 api://{client-id}/access_as_user
多IdP令牌验证 ✅ 工作中 Entra v1.0/v2.0+Cognito JWTs
A2A协议 ✅ 工作 代理卡发现、消息/发送
ADK+克劳德·海库4.5 ✅ 工作 通过LiteLLM在AWS基岩上
MCP工具(无状态) ✅ 正在工作 通过header_provider传递的令牌
多回合对话 ✅ 工作 会话状态保留在ADK中
RBAC执行 ✅ 工作 三层访问控制
海外建筑运营管理局代币交换 ✅ 工作 通过On-Behalf-Of流绘制API图形
S3工具 ✅ 工作 服务器端AWS凭据
X—承担角色 ✅ 工作 端到端角色传播

已知限制

限制 影响
前端使用缓冲 /chat 不 /chat/stream 一次显示所有响应
内存中的会话服务 重新启动时丢失
JWKS缓存永远不会时间失效(A2A) 可能会出现过期密钥(未命中时自动清除)
未处理组超龄 Entra>记录了150个组,但未提取

架构图

系统架构```

┌─────────────────────────────────────────────────────────────────────────────────────┐
│ USER BROWSER │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │ React Frontend (Port 10003) │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────────────┐ │ │
│ │ │ MSAL.js │───▶│ Auth State │───▶│ Chat Interface │ │ │
│ │ │ (Login) │ │ (Token) │ │ - Send messages │ │ │
│ │ └──────────────┘ └──────────────┘ │ - Display responses │ │ │
│ │ │ │ │ - Scope selection │ │ │
│ │ ▼ ▼ └──────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Microsoft Entra ID (OAuth 2.0 + OIDC) │ │ │
│ │ │ - Token issuance (custom API scope + Graph scopes) │ │ │
│ │ │ - Group claims in token │ │ │
│ │ └─────────────────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────┘
│
│ HTTP POST + Bearer Token
▼
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ A2A Gateway (Port 10000) │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ auth_middleware │ │
│ │ 1. Validate JWT signature (JWKS from Entra ID) │ │
│ │ 2. Check blocklist (BLOCKED_USERS) │ │
│ │ 3. Verify group membership (ALLOWED_GROUPS) │ │
│ │ 4. Set ContextVar: current_user_claims, current_access_token │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ IdentityAwareAgentExecutor │ │
│ │ 1. Extract user claims from ContextVar │ │
│ │ 2. Ensure ADK session exists for user │ │
│ │ 3. Forward request to ADK Agent │ │
│ │ 4. Emit TaskStatusUpdateEvent with response │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────┘
│
│ HTTP POST + Bearer Token
▼
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ ADK Agent (Port 10001) │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ Session Management │ │
│ │ - InMemorySessionService │ │
│ │ - Session state: user:access_token, user:email, user:role, user:groups │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ LlmAgent (Claude Haiku 4.5 via LiteLLM) │ │
│ │ - Processes user message │ │
│ │ - Decides which tools to call │ │
│ │ - Formats final response │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────┐ ┌────────────────────────────────────────────────┐ │
│ │ Local Tools │ │ McpToolset │ │
│ │ - get_identity_info │ │ - header_provider injects Bearer token │ │
│ │ - check_my_permissions│ │ - Calls FastMCP server │ │
│ └────────────────────────┘ └────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────┘
│
│ HTTP POST + Bearer Token (from header_provider)
▼
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ FastMCP Server (Port 10002) │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ FastMCP Built-in Auth (MultiAuth) │ │
│ │ 1. AzureJWTVerifier (v2.0) — auto-configured from Azure app registration │ │
│ │ 2. JWTVerifier (v1.0 fallback) — for sts.windows.net issuer tokens │ │
│ │ 3. Validates JWT signature, issuer, audience, expiry via JWKS │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ UserContextMiddleware │ │
│ │ 1. Detect IdP provider from iss claim (entra/cognito/auth0) │ │
│ │ 2. Extract email, groups from validated token claims │ │
│ │ 3. Resolve available roles via TomlPolicyEvaluator (permissions.toml) │ │
│ │ 4. Validate X-Assume-Role header against available roles │ │
│ │ 5. Set ContextVars: current_user_token, current_user_role, current_user_email│ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ Per-Tool Auth Decorators │ │
│ │ 1. auth=require_role() checks user role via ContextVar │ │
│ │ 2. Raises ToolError with [TOOL_DENIAL] prefix on denial │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ MCP Tools │ │
│ │ - get_user_profile (all roles) │ │
│ │ - list_files (admin, developer) │ │
│ │ - send_email (admin only) │ │
│ │ - delete_resource (admin only) │ │
│ │ - get_current_time (admin only) │ │
│ │ - convert_timezone (admin only) │ │
│ │ - get_time_difference (admin only) │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────┘
│
│ (Optional) Graph API calls with user token
▼
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ Microsoft Graph API │
│ - /me (User.Read scope) │
│ - /me/drive/root/children (Files.Read scope) │
│ - /me/sendMail (Mail.Send scope) │
└─────────────────────────────────────────────────────────────────────────────────────┘


### 请求流程图```
┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  User    │     │ Frontend │     │   A2A    │     │   ADK    │     │   MCP    │
│ Browser  │     │  React   │     │ Gateway  │     │  Agent   │     │  Server  │
└────┬─────┘     └────┬─────┘     └────┬─────┘     └────┬─────┘     └────┬─────┘
│                │                │                │                │
│  1. Login      │                │                │                │
│───────────────▶│                │                │                │
│                │ 2. MSAL        │                │                │
│                │ acquireToken   │                │                │
│                │───────────────▶│ Entra ID      │                │
│                │◀───────────────│ (Token)       │                │
│                │                │                │                │
│  3. Send msg   │                │                │                │
│───────────────▶│                │                │                │
│                │ 4. POST /      │                │                │
│                │ + Bearer token │                │                │
│                │───────────────▶│                │                │
│                │                │ 5. Validate    │                │
│                │                │    JWT         │                │
│                │                │ 6. Check       │                │
│                │                │    groups      │                │
│                │                │                │                │
│                │                │ 7. POST /chat  │                │
│                │                │ + Bearer token │                │
│                │                │───────────────▶│                │
│                │                │                │ 8. Store token │
│                │                │                │    in session  │
│                │                │                │                │
│                │                │                │ 9. LLM decides │
│                │                │                │    tool call   │
│                │                │                │                │
│                │                │                │ 10. MCP call   │
│                │                │                │ + Bearer token │
│                │                │                │───────────────▶│
│                │                │                │                │ 11. Validate
│                │                │                │                │     JWT
│                │                │                │                │ 12. Check
│                │                │                │                │     role
│                │                │                │                │ 13. Execute
│                │                │                │                │     tool
│                │                │                │◀───────────────│
│                │                │                │ 14. Tool result│
│                │                │                │                │
│                │                │                │ 15. LLM formats│
│                │                │                │     response   │
│                │                │◀───────────────│                │
│                │                │ 16. Response   │                │
│                │◀───────────────│                │                │
│                │ 17. A2A result │                │                │
│◀───────────────│                │                │                │
│ 18. Display    │                │                │                │
│                │                │                │                │

身份验证流程

系统使用 使用PKCE的OAuth 2.0授权代码流 通过Microsoft Entra ID。MSAL.js 3.6处理前端流——不使用隐式授权。令牌是包含OAuth 2.0/OIDC声明的标准JWT(iss, aud, exp, scp, groups, preferred_username等等),并在每一层使用提供商的JWKS公钥进行验证。

初始身份验证```

  1. User clicks "Sign In with Microsoft"
  2. MSAL.js opens popup to Entra ID login (Authorization Code + PKCE)
  3. User authenticates with credentials/MFA
  4. Entra ID returns an authorization code to the SPA
  5. MSAL.js exchanges the code for tokens (PKCE-secured, no client secret):
    - ID Token (OIDC — user identity claims)
    - Access Token (OAuth 2.0 — with custom API scope + Graph scopes)
  6. MSAL.js caches tokens in browser storage
  7. Frontend shows authenticated state

### 请求令牌获取```javascript
// Frontend: authConfig.js
const API_SCOPE = `api://${clientId}/access_as_user`;

export const graphScopes = {
basic: [API_SCOPE, 'User.Read'],
files: [API_SCOPE, 'User.Read', 'Files.Read'],
email: [API_SCOPE, 'User.Read', 'Mail.Send'],
full: [API_SCOPE, 'User.Read', 'Files.Read', 'Mail.Send'],
destructive: [API_SCOPE, 'User.Read', 'Files.Read', 'Files.ReadWrite.All', 'Mail.Send'],
};

// Token acquisition (cached, no re-prompt unless expired)
const token = await instance.acquireTokenSilent({ scopes, account });

令牌格式和验证

访问令牌是 JWT(JSON Web令牌) 由Entra ID使用RS256签名。每个后端层通过从Microsoft的JWKS端点获取公钥并验证签名、颁发者、受众和到期时间来独立验证Bearer令牌。Entra ID可以发行v1.0代币(发行人: sts.windows.net/{tenant}/)或v2.0令牌(发行者: login.microsoftonline.com/{tenant}/v2.0)--两者都支持。

A2A服务器 --手动JWT验证:```python

a2a_server/server.py — manual JWKS fetching, supports v1.0 and v2.0 tokens

JWKS_URIS = [
f"https://login.microsoftonline.com/{TENANT_ID}/discovery/v2.0/keys",
f"https://login.microsoftonline.com/{TENANT_ID}/discovery/keys",
"https://login.microsoftonline.com/common/discovery/keys",
]
VALID_ISSUERS = [
f"https://login.microsoftonline.com/{TENANT_ID}/v2.0",
f"https://sts.windows.net/{TENANT_ID}/",
]


**MCP 服务器** --FastMCP 3.1内置身份验证 `MultiAuth`:```python
# mcp_server/server.py — uses FastMCP's built-in auth providers
# v2.0 verifier (primary)
AzureJWTVerifier(client_id=CLIENT_ID, tenant_id=TENANT_ID, required_scopes=["access_as_user"])

# v1.0 verifier (fallback for sts.windows.net issuer tokens)
JWTVerifier(
jwks_uri=f"https://login.microsoftonline.com/{TENANT_ID}/discovery/keys",
issuer=f"https://sts.windows.net/{TENANT_ID}/",
audience=[CLIENT_ID, f"api://{CLIENT_ID}"],
required_scopes=["access_as_user"],
)
# Composed via MultiAuth — tries v2.0 first, falls back to v1.0

多回合对话流程

根据请求重新验证令牌

层 动作 频率 缓存?
前端 acquireTokenSilent() 每个请求 是(SWITCHache)
A2A服务器 JWT签名验证 每个请求 JWKS缓存
A2A服务器 组成员资格检查 每个请求 否
ADK代理 在会话中存储令牌 每个请求 会话状态
MCP 服务器 JWT签名验证 每次工具调用 JWKS缓存
MCP 服务器 角色权限检查 每次工具调用 否

ADK中的会话状态```python

Session state stored with user: prefix for persistence

session.state = {
"user:access_token": "", # Updated each request
"user:email": "user@domain.com",
"user:name": "User Name",
"user:groups": ["group-id-1", "group-id-2"],
"user:role": "admin" # Derived from groups
}


### 多转弯示例```
Turn 1: "What's my email?"
├─ Token validated at A2A (cached JWKS)
├─ Session created in ADK
├─ Local tool: get_identity_info
└─ Response: "Your email is user@domain.com"

Turn 2: "What time is it in Tokyo?"
├─ Token validated at A2A (same JWKS)
├─ Session retrieved (same session_id)
├─ Token updated in session state
├─ MCP tool: get_current_time
│   ├─ Token validated at MCP (cached JWKS)
│   └─ Role check: admin required ✓
└─ Response: "The time in Tokyo is..."

Turn 3: "List my files"
├─ Token validated at A2A
├─ Session retrieved
├─ MCP tool: list_files
│   ├─ Token validated at MCP
│   └─ Role check: admin/developer required ✓
└─ Response: "Your files are..."

上下文和身份传递

A2A服务器→ ADK代理```python

A2A Server uses ContextVar to pass auth data

current_user_claims: ContextVar[dict] = ContextVar("current_user_claims", default={})
current_access_token: ContextVar[str] = ContextVar("current_access_token", default="")

Set in auth_middleware

current_user_claims.set(claims)
current_access_token.set(token)

Read in IdentityAwareAgentExecutor

user_claims = current_user_claims.get()
access_token = current_access_token.get()

Forward to ADK Agent via HTTP

POST /chat
{
"message": "user message",
"user_id": "sub-claim-value",
"session_id": "session-uuid"
}
Headers: Authorization: Bearer


### ADK代理→ MCP 服务器```python
# McpToolset uses header_provider for dynamic auth
def mcp_header_provider(readonly_context: ReadonlyContext) -> Dict[str, str]:
if readonly_context and readonly_context.state:
access_token = readonly_context.state.get("user:access_token", "")
if access_token:
return {"Authorization": f"Bearer {access_token}"}
return {}

# McpToolset configuration
self.mcp_toolset = McpToolset(
connection_params=StreamableHTTPConnectionParams(url=MCP_SERVER_URL),
header_provider=mcp_header_provider,  # Injects token per-request
)

MCP服务器上下文变量```python

MCP Server stores validated claims in ContextVar (stateless mode — no ctx.get_state())

current_user_token: ContextVar[str] = ContextVar("current_user_token", default="")
current_user_role: ContextVar[str] = ContextVar("current_user_role", default="none")
current_user_email: ContextVar[str] = ContextVar("current_user_email", default="")

Set by UserContextMiddleware, read by tools and auth= callables

@mcp.tool(auth=require_role("admin"))
async def get_current_time(timezone: str = "UTC") -> dict:
user_role = current_user_role.get()
user_email = current_user_email.get()

... tool logic


______________________________________________________________________

## RBAC(基于角色的访问控制)

### 角色继承```
admin      → Full access to all tools
developer  → Access to profile and file tools
viewer     → Access to profile tools only
none       → No tool access (agent-level denied)

组到角色映射(permissions.toml)

角色定义见 permissions.toml (代理人所有,未经授权)。复制自 permissions.example.toml:```toml

permissions.toml — Agent-owned role assignments

Group-to-role mapping is the PRIMARY mechanism.

User-level overrides are optional for exceptions.

[group_rules.entra]
"" = "admin"
"" = "developer"
"" = "viewer"

[group_rules.cognito]

"platform-admins" = "admin" # Future: Cognito groups

[group_rules.auth0]

"admin" = "admin" # Future: Auth0 roles

[users]

Optional direct user overrides (case-insensitive email lookup)

"user@company.com" = { role = "admin" }

[defaults]
unknown_users = "none"


这 `TomlPolicyEvaluator` (`mcp_server/policy.py`)通过文件更改时的热重新加载,从组声明和用户覆盖中解析可用角色。角色优先级:管理员>开发人员>查看器。

**角色选择**:用户必须设置 `X-Assume-Role` MCP工具调用的标题。 `UserContextMiddleware` 根据可用角色验证假定的角色。对于工具列表,将自动使用优先级最高的角色。

> **备注**:A2A服务器仍在使用 `GROUP_TO_ROLE` 来自env变量(`ADMIN_GROUP_ID`等等)用于代理级访问控制。MCP服务器使用 `permissions.toml` 用于工具级RBAC。

### 工具权限矩阵

|工具|允许的角色|描述|
|------|---------------|-------------|
| `get_user_profile` |管理员、开发人员、查看器|获取Microsoft Graph配置文件(或令牌声明回退)|
| `list_files` |管理员、开发人员|列出OneDrive文件|
| `send_email` |admin |通过Graph发送电子邮件|
| `delete_resource` |admin |删除资源|
| `get_current_time` |admin |获取时区时间|
| `convert_timezone` |admin |时区转换|
| `get_time_difference` |admin |比较时区偏移|

### 权限执行代码```python
# MCP Server: Per-tool auth= decorators (require_role only — IdP scope checking removed)
@mcp.tool(auth=require_role("admin", "developer", "viewer"))
async def get_user_profile() -> dict: ...

@mcp.tool(auth=require_role("admin", "developer"))
async def list_files(folder_path: str = "/") -> dict: ...

@mcp.tool(auth=require_role("admin"))
async def send_email(to: str, subject: str, body: str) -> dict: ...

# Auth helper
def require_role(*allowed_roles):
# Reads current_user_role ContextVar (set by UserContextMiddleware)
# Raises: "[TOOL_DENIAL] Access denied: Role '...' cannot use this tool. Required roles: [...]"
...

拒绝访问示例```

No X-Assume-Role header:
→ [ROLE_SELECTION] Role selection required. Set X-Assume-Role header to one of: ['admin']

Viewer tries to list files:
→ [TOOL_DENIAL] Access denied: Role 'viewer' cannot use this tool. Required roles: ['admin', 'developer']

Developer tries to send email:
→ [TOOL_DENIAL] Access denied: Role 'developer' cannot use this tool. Required roles: ['admin']

User tries to assume a role they don't have:
→ [TOOL_DENIAL] Cannot assume role 'admin'. Available roles: ['developer']

No-group user (not in permissions.toml):
→ [TOOL_DENIAL] No roles available for user@domain.com. Contact admin to assign group membership.

User without groups at A2A gateway:
→ 403 {"error": "access_denied", "denial_level": "agent", "denial_reason": "no_group_membership"}

Blocked user:
→ 403 {"error": "access_denied", "denial_level": "agent", "denial_reason": "blocked_user"}


______________________________________________________________________

## API 参考

### A2A服务器(端口10000)

#### 代理卡发现```http
GET /.well-known/agent-card.json

答复:```json
{
"name": "Identity-Aware AI Agent",
"description": "An AI agent with Entra ID authentication...",
"url": "http://localhost:10000/",
"version": "1.0.0",
"capabilities": {"streaming": true},
"skills": [...]
}


#### 发送消息(A2A协议)```http
POST /
Authorization: Bearer
Content-Type: application/json

{
"jsonrpc": "2.0",
"method": "message/send",
"params": {
"message": {
"messageId": "msg-123",
"role": "user",
"parts": [{"type": "text", "text": "What time is it?"}]
}
},
"id": "req-123"
}

答复:```json
{
"id": "req-123",
"jsonrpc": "2.0",
"result": {
"id": "task-uuid",
"kind": "task",
"status": {
"state": "completed",
"message": {
"kind": "message",
"role": "agent",
"parts": [{"kind": "text", "text": "The current time is..."}]
}
}
}
}


#### 健康检查```http
GET /health

安全上下文```http

GET /me
Authorization: Bearer


答复:```json
{
"user": { "email": "user@domain.com", "name": "User Name", "oid": "..." },
"security": {
"role": "developer",
"groups": ["group-id-1"],
"group_names": { "group-id-1": "developer" },
"token_scopes": ["User.Read", "Files.Read"],
"token_expiry": 1741363200,
"issuer": "https://login.microsoftonline.com/{tenant}/v2.0"
},
"permissions": {
"get_user_profile": true, "list_files": true, "send_email": false,
"delete_resource": false, "get_current_time": false,
"convert_timezone": false, "get_time_difference": false
},
"tool_scopes": {
"get_user_profile": ["User.Read"], "list_files": ["Files.Read"],
"send_email": ["Mail.Send"], "delete_resource": ["Files.ReadWrite.All"],
"get_current_time": [], "convert_timezone": [], "get_time_difference": []
}
}

ADK代理(端口10001)

创建会话```http

POST /session
Authorization: Bearer
Content-Type: application/json

{
"user_id": "user-sub-claim",
"user_info": {
"email": "user@domain.com",
"name": "User Name",
"groups": ["group-id-1"]
}
}


答复:```json
{"session_id": "session-uuid"}

聊天```http

POST /chat
Authorization: Bearer
Content-Type: application/json

{
"message": "What's my email?",
"user_id": "user-sub-claim",
"session_id": "session-uuid"
}


答复:```json
{
"response": "Your email is user@domain.com",
"session_id": "session-uuid"
}

MCP服务器(端口10002)

MCP端点```http

POST /mcp
Authorization: Bearer
Content-Type: application/json

Standard MCP protocol messages


#### 可用工具

|工具|参数|返回|
|------|------------|---------|
| `get_user_profile` |(无)|来自Graph或令牌声明的用户配置文件|
| `list_files` | `folder_path?: string` |文件名列表|
| `send_email` | `to, subject, body` |发送状态|
| `delete_resource` | `resource_id` |删除状态|
| `get_current_time` | `timezone?: string` |带纪元的时间信息|
| `convert_timezone` | `time_str, from_timezone, to_timezone` |转换时间|
| `get_time_difference` | `timezone1, timezone2` |偏移差|

______________________________________________________________________

## 安装指南

### 先决条件

- Python 3.10+
- Node.js 18+
- Microsoft Entra ID租户
- Anthropic API密钥(用于Claude)

### 1.微软Entra ID配置

1. 在中创建应用程序注册 Entra管理中心
1. 配置平台:单页应用
- 重定向URI: `http://localhost:10003`, `http://localhost:10003/redirect`
1. 公开API:
- 添加范围: `access_as_user`
- 应用程序ID URI: `api://{client-id}`
1. API权限:
- `openid`, `profile`, `User.Read`, `Files.Read`, `Mail.Send`
1. 令牌配置:
- 添加组声明(安全组)
1. 创建安全组:
- 管理员组、开发人员组、查看器组

### 2.环境设置```bash
# Backend (.env)
cp .env.example .env

# Required variables:
ENTRA_CLIENT_ID=
ENTRA_TENANT_ID=
ADMIN_GROUP_ID=
DEVELOPER_GROUP_ID=
VIEWER_GROUP_ID=
ANTHROPIC_API_KEY=

# Frontend (frontend/.env)
cd frontend && cp .env.example .env

REACT_APP_ENTRA_CLIENT_ID=
REACT_APP_ENTRA_TENANT_ID=

# MCP Permissions (group-to-role mapping)
cp permissions.example.toml permissions.toml
# Edit permissions.toml with your Entra ID security group GUIDs

3.安装依赖项```bash

Backend

pip install -r requirements.txt

or with uv:

uv pip install -r requirements.txt

Frontend

cd frontend && npm install


### 4.运行服务```bash
# Terminal 1: MCP Server
uv run python mcp_server/server.py

# Terminal 2: ADK Agent
uv run python adk_agent/agent.py

# Terminal 3: A2A Gateway
uv run python a2a_server/server.py

# Terminal 4: Frontend
cd frontend && npm start

5.访问申请

  • 前端:http://localhost:10003
  • A2A网关:http://localhost:10000
  • 代理卡:http://localhost:10000/.well-已知/代理卡.json

安全测试仪表板

前端包括一个全面的安全测试仪表板,用于测试和可视化三层访问控制系统。

仪表板组件

组件 位置 目的
安全上下文面板 左侧边栏 显示角色、组、范围、令牌到期倒计时
令牌检查器 左侧边栏(可折叠) 解码JWT标头/有效载荷以供显示
RBAC测试矩阵 左侧边栏 一键式测试网格,带通过/失败跟踪
对话选项卡 主区域 多选项卡聊天,每个选项卡范围选择(最多4个)
审核日志 主区域(底部) 拒绝分类的请求历史记录
拒绝指示器 内联徽章 颜色编码的拒绝层:代理(红色)、工具(橙色)、资源(紫色)
帐户切换器 标题 支持多帐户以测试不同角色

拒绝分类

拒绝被自动分为四个等级:

层 检测者 示例
代理 http401/403+ denial_level 在响应正文中 用户不在任何组中
工具 [TOOL_DENIAL] 响应文本中的标记 查看器正在尝试 list_files
RESOURCE 响应文本中的Graph API 403 Graph权限不足

前端文件结构```

frontend/src/
App.js # Dashboard layout shell
App.css # Dark theme styles
authConfig.js # MSAL config + scope presets (basic, files, email, full, destructive)
index.js # MSAL provider setup
components/
AuthStatus.js # Multi-account switcher dropdown
LoginPrompt.js # Sign-in prompt
SecurityContextPanel.js # Role, groups, scopes, expiry countdown
TokenInspector.js # JWT decoder display
ConversationTabs.js # Multi-tab chat with per-tab scope
ChatInterface.js # Chat with denial tagging and latency tracking
RBACTestMatrix.js # One-click test grid
AuditLog.js # Request history table
DenialIndicator.js # Color-coded denial badge
utils/

…(正文过长,页面只展示前面部分,完整内容见仓库)
```

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Sts Entraid Single A2a Adkagent MCP Poc 怎么安装?

在客户端按下面的安装命令接入:pip install -r requirements.txt。装完在客户端配置里引用同一个包或端点。

Sts Entraid Single A2a Adkagent MCP Poc 怎么在 Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Sts Entraid Single A2a Adkagent MCP Poc 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Sts Entraid Single A2a Adkagent MCP Poc 需要 API Key 吗?

资料标注需要OAuth 授权认证,使用前准备好对应凭据,并按最小权限配置。

Sts Entraid Single A2a Adkagent MCP Poc 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Sts Entraid Single A2a Adkagent MCP Poc 能提供哪些能力?

资料显示约 7 个工具;能力标签包括 AI代理、访问控制、Claude。具体工具清单以官方文档为准。

Sts Entraid Single A2a Adkagent MCP Poc 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

Sts Entraid Single A2a Adkagent MCP Poc 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。