foundry agents with obo MCP server

具有代表（OBO）身份验证的Microsoft Foundry代理

此存储库提供了示例代码和全面的说明，用于设置Microsoft Foundry代理，这些代理使用代表（OBO）身份验证流通过MCP（模型上下文协议）服务器安全访问第三方服务。

______________________________________________________________________

目录

• 概述
• 建筑
• 先决条件
• 存储库结构
• 安装说明

- 1.用户设置 - 2.Atlassian MCP服务器设置 - 3.Microsoft结构数据代理设置 - 4.部署Azure AI Foundry资源 - 5.在Foundry中配置MCP工具 - 6.创建Foundry代理 - 7.运行示例应用程序

• 测试OBO流量
• 故障排除
• 额外资源
• 许可证

______________________________________________________________________

概述

通过代理访问数据是Microsoft Foundry的一项关键功能。代理可以使用MCP工具从各种来源访问数据。在数据源是第三方服务的情况下，确保数据访问安全并遵循最小特权原则至关重要。

这 代表（OBO）身份验证流程 允许Foundry代理代表登录用户访问第三方服务，确保：

• 数据访问基于用户身份进行控制
• 执行行级安全策略
• 所有访问都是可审计的

此存储库演示了什么

1. Atlassian集成：一个定制的MCP服务器，将Atlassian Jira和Confluence REST API封装在OBO令牌验证中
2. Microsoft结构集成：使用带OBO流的结构数据代理MCP工具对Lakehouse数据实施行级安全
3. 工具级别授权：将MCP授权中间件用于检查用户许可证的自定义工具，并仅向代理公开允许的工具。例如：

- 高级用户可以访问Atlassian Jira、Confluence和Fabric Data Agent工具。 - 免费增值用户只能访问Atlassian Jira和Fabric Data Agent工具。

______________________________________________________________________

建筑

┌─────────────────┐     ┌──────────────────────┐     ┌─────────────────────────┐
│   React SPA     │────▶│  FastAPI Backend     │────▶│  Azure AI Foundry       │
│  (MSAL Auth)    │     │  (Token Validation)  │     │  Agent Service          │
└─────────────────┘     └──────────────────────┘     └───────────┬─────────────┘
                                                                 │
                              ┌──────────────────────────────────┼──────────────────────────────────┐
                              │                                  │                                  │
                              ▼                                  ▼                                  │
                 ┌─────────────────────────┐      ┌─────────────────────────┐                       │
                 │  Custom Atlassian MCP   │      │  Fabric Data Agent MCP  │                       │
                 │  Server (Azure ACA)     │      │  (Microsoft Managed)    │                       │
                 └───────────┬─────────────┘      └───────────┬─────────────┘                       │
                             │                                │                                     │
                             ▼                                ▼                                     │
                 ┌─────────────────────────┐      ┌─────────────────────────┐                       │
                 │  Atlassian Cloud        │      │  Microsoft Fabric       │                       │
                 │  (Jira & Confluence)    │      │  Lakehouse (with RLS)   │                       │
                 └─────────────────────────┘      └─────────────────────────┘                       │

此架构使用具有多个MCP工具的单个代理来访问Atlassian和Microsoft Fabric Lakehouse的数据。 以下是代理用于确定使用哪个工具的示例提示：

You are a tool use assistant.
You can answer questions based on the tools attached to you. 
Only use the tools to get information and answer questions.
If the tool returns URLs, format them as clickable links in markdown.
Always state the tool you are using.
If you cannot find the answer using the tools, respond with "I don't know". 

关键组件

______________________________________________________________________

先决条件

所需帐户和订阅

必需的权限

开发工具

Python依赖关系

MCP 服务器 (custom_jira_confluence_mcp_server/requirements.txt):

fastapi>=0.110
uvicorn[standard]>=0.29
httpx[socks,http2]
fastmcp
python-dotenv
pydantic

后端API (foundry_agent_backend_api/requirements.txt):

fastapi
uvicorn
pyjwt
cryptography
azure-ai-projects>=2.0.0b1
python-dotenv

代理脚本 (foundry_agents/requirements.txt):

azure-ai-projects
python-dotenv

Node.js依赖关系

React SPA使用：

• @azure/msal-browser ^4.27.0
• @azure/msal-react ^3.0.23
• react ^19.2.3

______________________________________________________________________

存储库结构

├── bicep-basic-agent-setup/          # Basic Foundry deployment template
├── bicep-standard-agent-setup/       # Standard Foundry deployment with dependencies
│   ├── main.bicep
│   ├── azuredeploy.json
│   └── modules-standard/             # Bicep modules for role assignments
├── custom_jira_confluence_mcp_server/
│   ├── atlassian_mcp_server_jira_confl.py  # MCP server implementation
│   ├── Dockerfile
│   ├── docker_build.ps1              # Windows deployment script
│   ├── docker_build.sh               # Linux/macOS deployment script
│   └── requirements.txt
├── foundry_agent_backend_api/
│   ├── foundry_agent_server.py       # FastAPI backend
│   └── requirements.txt
├── foundry_agents/
│   ├── create_multitool_prompt_agent.py  # Agent creation script
│   └── requirements.txt
├── spa_foundry_agent_webapp/
│   ├── src/
│   │   ├── App.js                    # Main React component
│   │   └── authConfig.js             # MSAL configuration
│   └── package.json
├── sample_data/
│   └── invoices/                     # Sample invoice data for Fabric
└── images/                           # Documentation screenshots

______________________________________________________________________

安装说明

1.用户设置

创建测试用户以演示OBO流程和行级安全性：

1. 微软Entra用户：在Microsoft Entra租户中创建两个用户（UserA和UserB）

1. 结构工作区访问：使用查看器权限将UserA和UserB添加到结构工作区。确保他们至少可以登录一次Fabric门户。

1. Atlassian用户：在中创建相应的帐户 Atlassian云

- 创建示例Jira项目和问题 - 创建示例Confluence空间和页面 - 记下用户唯一标识符（user_sub），以更新custom_jira_confluence_mcp_server目录中的user_access_list.json。 - 引导到 Atlassian管理员 → 用户→ 选择用户→ URL末尾将有用户ID：例如。557058:d665a061-d4e6-4561-a263-202befc4db75 alt text

1. 身份流：在海外建筑运营管理局流程中：

- Atlassian用户身份用于Jira/Confluence数据访问 - Microsoft身份用于Foundry代理服务和结构数据代理身份验证

______________________________________________________________________

2.Atlassian MCP服务器设置

2.1创建Atlassian OAuth应用程序

1. 导航到 Atlassian开发人员控制台

1. 创建新的OAuth 2.0应用程序：

Create Atlassian App

1. 为Confluence和Jira配置API作用域：

Jira范围：

Jira Scopes

汇流范围：

Confluence Scopes

1. 配置授权设置：

Authorization Settings

1. 复制 客户端ID 供以后使用：

Client ID

2.2构建和部署MCP服务器

自定义MCP服务器使用封装Atlassian REST API 快速MCP。它在将请求转发到Atlassian之前验证传入的OBO令牌。

部署步骤：

1. 导航到MCP服务器目录：

   cd custom_jira_confluence_mcp_server

1. 创建环境文件：

   cp .env.sample .env

1. 配置 .env 文件：

   ATLASSIAN_CLIENT_ID=

1. 使用Docker部署到Azure容器应用程序：

Windows（PowerShell）：

   .\docker_build.ps1 -AcrName  -ImageName  -ImageVersion 

Linux/macOS：

   chmod +x docker_build.sh
   ./docker_build.sh -a  -i  -v 

选项：

1. 验证部署：

Container App Logs

在没有有效令牌的情况下访问MCP服务器端点应返回 401 Unauthorized:

401 Response

______________________________________________________________________

3.Microsoft结构数据代理设置

3.1创建湖屋

1. 在Microsoft Fabric中创建一个湖屋 湖屋入门

1. 启用 用户身份模式 在SQL Analytics端点上：

User Identity Mode

3.2加载样本数据

1. 从上传示例发票数据 sample_data/invoices/ 前往您的湖畔小屋：

Upload Data

1. 将数据加载到增量表中：

Load to Table

1. 验证表架构：

Table Schema

3.3配置行级安全

1. 跟随 OneLake安全文档 设置RLS

1. 创建两个数据访问角色：

RoleA Configuration

RoleB Configuration

3.4创建和发布数据代理

1. 将数据代理添加到发票表中：

Add Data Agent

1. 配置代理说明：

   You are an Invoice Data agent. You can answer questions about Invoice and nothing else. 
   Use the provided invoices table data to answer. If you cannot answer, state that you can 
   answer questions only about invoices.

Agent Instructions

1. 发布数据代理 并保存连接详细信息：

从URL：

   https://api.fabric.microsoft.com/v1/workspaces/{workspace_id}/dataagents/{artifact_id}/aiassistant/openai

Published Data Agent

______________________________________________________________________

4.部署Azure AI Foundry资源

使用二头肌模板将Foundry资源部署到标准代理项目中。

1. 创建资源组：

   az group create --name  --location westus

1. 部署模板：

   cd bicep-standard-agent-setup
   az deployment group create --resource-group  --template-file main.bicep

> 必需的权限：Azure AI帐户所有者、基于角色的访问管理员

有关详细说明，请参阅 肱二头肌标准代理设置README.

1. 将用户分配到Foundry项目:

- 将UserA和UserB添加到项目中 Azure人工智能用户 角色 - 确保这些用户与之前创建的Microsoft Entra用户匹配

______________________________________________________________________

5.在Foundry中配置MCP工具

5.1创建Atlassian MCP工具

1. 在Foundry中，导航到 构建 → 工具 → 自定义 → MCP工具

1. 配置OAuth身份通道：

MCP Tool Configuration

> 备注：Foundry代理服务启动OBO流，并将ID令牌和访问令牌存储在其令牌缓存中。当MCP工具被调用时，它会发送访问令牌。自定义MCP服务器验证访问令牌，并将请求转发给Atlassian REST API。

1. 点击 连接 并复制同意URL：

Consent URL

1. 将同意URL添加到您的Atlassian应用程序 回调URL:

Callback URL

重要：这建立了Foundry代理服务和Atlassian Auth之间的双向信任。同样的方法也适用于支持海外建筑运营管理流程的其他第三方服务。

5.2创建结构数据代理MCP工具

1. 在Foundry中，导航到 构建 → 工具 → 结构数据代理

1. 从已发布的数据代理中输入工作区ID和工件ID

1. 点击 连接 并复制 项目连接ID:

Fabric Connection ID

备注：此设置不需要Microsoft Entra应用程序注册，因为结构数据代理MCP工具本机使用Microsoft Identity平台。

______________________________________________________________________

6.创建Foundry代理

1. 导航到代理脚本目录：

   cd foundry_agents

1. 配置环境：

   cp .env.sample .env

1. 编辑 .env 与你的价值观：

   foundry_account_name="your_foundry_account_name"
   foundry_project_name="your_foundry_project_name"
   foundry_resource_group="your_foundry_resource_group"
   foundry_subscription_id="your_foundry_subscription_id"
   agent_name="your_agent_name"
   fabrric_data_mcp_tool_name="fabric_data_agent_connection_name"
   mcp_tool_server_name="atlassian_mcp_tool_connection_name"
   mcp_tool_server_url="https://your-mcp-server-url/mcp"

1. 创建并激活虚拟环境：

   python -m venv venv

   # Windows
   venv\Scripts\activate

   # Linux/macOS
   source venv/bin/activate

1. 安装依赖项并创建代理：

   pip install -r requirements.txt
   python create_multitool_prompt_agent.py

______________________________________________________________________

7.运行示例应用程序

7.1启动后端API

1. 导航到后端目录：

   cd foundry_agent_backend_api

1. 创建和配置环境：

   cp .env.sample .env

编辑 .env:

   tenant_id="your_entra_tenant_id"
   foundry_account_name="your_foundry_account_name"
   foundry_project_name="your_foundry_project_name"

1. 设置虚拟环境：

   python -m venv .venv

   # Windows
   .venv\Scripts\activate

   # Linux/macOS
   source .venv/bin/activate

1. 安装依赖项并启动服务器：

   pip install -r requirements.txt --pre
   uvicorn foundry_agent_server:app --reload --port 8765

7.2配置和启动Web应用程序

1. 创建应用程序注册 在微软Entra中：

- 应用程序类型：单页应用程序（SPA） - 重定向URI: http://localhost:3000 - API权限：添加的委派权限 Azure机器学习服务

API Permissions

1. 更新 spa_foundry_agent_webapp/src/authConfig.js:

   export const msalConfig = {
     auth: {
       clientId: "",
       authority: "https://login.microsoftonline.com/",
       redirectUri: "http://localhost:3000",
     },
     cache: {
       cacheLocation: "sessionStorage",
       storeAuthStateInCookie: false,
     },
   };

   export const loginRequest = {
     scopes: ["api:///read"],
   };

1. 启动web应用程序：

   cd spa_foundry_agent_webapp
   npm install
   npm start

______________________________________________________________________

测试OBO流量

测试场景1：Atlassian集成

1. 以以下身份登录到web应用程序 乌谢拉区:

Sign In

1. 输入您的代理人姓名，并就Jira问题提问：

Chat Interface

> 备注：当问到Jira问题时，Foundry代理会触发OAuth流，为Atlassian MCP服务器获取OBO令牌。MCP服务器验证令牌并将请求转发给Jira REST API。

1. 完成Atlassian OAuth同意流程：

Consent Prompt

1. 选择您的Atlassian网站并授权：

Site Selection

Authorization

1. 点击 “我已完成登录” 并批准工具使用：

Tool Approval

1. 根据您的Atlassian权限查看结果：

Jira Results

测试场景2：带RLS的结构数据代理

1. 询问发票数据：

   Invoice count

1. 乌谢拉区 看到筛选到客户ID 834的发票（1054条记录）：

UserA Results

1. 用户B 看到筛选到客户ID 821的发票（1025条记录）：

UserB Results

这表明，通过OBO流，行级安全性是基于经过身份验证的用户身份来实施的。

______________________________________________________________________

故障排除

______________________________________________________________________

额外资源

• Azure AI Foundry文档
• Microsoft结构数据代理
• Atlassian OAuth 2.0（3LO）
• MSAL.js for React
• FastMCP文档

______________________________________________________________________

许可证

此项目作为示例代码提供，用于演示目的。请参考贵组织的生产使用许可要求。