通过

教程：为 Fabric 工作负荷创建Microsoft Entra 应用

本教程介绍如何为 Fabric 工作负荷创建和配置 Microsoft Entra 应用程序。 可以使用自动化脚本方法（建议）或按照手动步骤完全控制配置。

概述

Fabric 工作负荷需要Microsoft Entra 应用程序才能：

  • 对用户进行身份验证：为工作负荷用户启用单一登录（SSO）
  • Access Fabric API：代表用户调用 Microsoft Fabric API
  • 定义权限：指定工作负荷可以访问哪些资源
  • 启用安全通信：在工作负荷与 Fabric 平台之间建立信任

先决条件

在开始之前，请确保具备：

  • 已安装 Azure CLI：从 Azure CLI 文档下载
  • PowerShell 7.x 或更高版本：运行安装脚本所必需的
  • 租户管理员访问权限：或有权注册应用程序的帐户
  • 定义的工作负荷名称：遵循模式 Org.[YourWorkloadName]

扩展性工具包提供了一个自动化脚本，该脚本使用所有必需的设置创建和配置 Microsoft Entra 应用。

运行脚本

  1. 导航到脚本目录：

    cd scripts/Setup

  2. 运行 CreateDevAADApp 脚本：

    .\CreateDevAADApp.ps1

    或者，使用参数来避免提示：

    .\CreateDevAADApp.ps1 -ApplicationName "My Workload App" -WorkloadName "Org.MyWorkload" -TenantId "your-tenant-id"

  3. 出现提示时提供所需的信息：

    • 应用程序名称：Microsoft Entra 应用的显示名称（例如“我的分析工作负荷”）
    • 工作负荷名称：必须遵循模式 Org.[YourWorkloadName] （例如“Org.MyWorkload”）
    • 租户 ID：将在其中开发工作负荷的 Microsoft Entra ID 租户 ID

脚本输出

该脚本将提供基本信息：

ApplicationIdUri / Audience : api://localdevinstance/[tenant-id]/Org.MyWorkload/[random]
RedirectURI                : http://localhost:60006/close
Application Id             : [your-app-id]
secret                     : [your-app-secret]

脚本配置的内容

自动脚本设置：

身份验证配置

  • 重定向 URI：本地开发和 Fabric 平台网址
  • 受众 URI：遵循api://localdevinstance/[tenant-id]/[workload-name]/[random]模式的唯一标识符
  • 登录受众：多租户支持（AzureADMultipleOrgs）

API 权限

  • Microsoft Fabric： Fabric.Extend、工作区和项权限
  • Azure 存储： user_impersonation 用于 OneLake 访问
  • Microsoft Graph： User.Read 基本用户信息
  • Azure 数据资源管理器： user_impersonation 适用于 KQL 数据库

OAuth 权限范围 （用于远程托管）

  • FabricWorkloadControl：核心工作负荷功能
  • Item1.Read.All / Item1.ReadWrite.All：自定义项权限
  • FabricLakehouse.Read.All / FabricLakehouse.ReadWrite.All：湖仓访问
  • KQLDatabase.ReadWrite.All：KQL 数据库权限
  • FabricEventhouse.Read.All：Eventhouse 访问

预授权的应用程序

  • Microsoft Fabric 平台应用程序
  • Power BI 服务应用程序

方法 2：手动配置

** 如果您需要完全控制或更喜欢手动设置，请遵循以下详细步骤进行操作。

步骤 1：创建应用程序

  1. 登录到 Microsoft Azure 门户：导航到 Microsoft Azure 门户 并使用管理员帐户登录。

  2. 访问应用注册：

    • 转到 Azure Active Directory>应用注册
    • 选择“新建注册”

  3. 配置基本设置：

    • 名称：输入应用程序名称（例如“我的分析工作负荷”）
    • 支持的帐户类型：选择“任何组织目录中的帐户（任何 Microsoft Entra ID 目录 - 多租户）”
    • 重定向 URI：暂时留空（稍后将添加）
    • 选择注册

步骤 2：配置身份验证

  1. 添加重定向 URI：

    • 在应用的菜单中转到 “身份验证 ”
    • 在 “平台配置”下，选择“ 添加平台”
    • 选择 单页应用程序（SPA）
    • 添加以下重定向 URI： 
      http://localhost:60006/close
https://app.powerbi.com/workloadSignIn/[YOUR-TENANT-ID]/[YOUR-WORKLOAD-NAME]
https://app.fabric.microsoft.com/workloadSignIn/[YOUR-TENANT-ID]/[YOUR-WORKLOAD-NAME]
https://msit.powerbi.com/workloadSignIn/[YOUR-TENANT-ID]/[YOUR-WORKLOAD-NAME]
https://msit.fabric.microsoft.com/workloadSignIn/[YOUR-TENANT-ID]/[YOUR-WORKLOAD-NAME]

  2. 配置令牌设置：

    • 在 隐式授权和混合流下，确保未选择任何选项（SPA 使用 PKCE）
    • 在 “高级设置”下，启用 “允许公共客户端流：否”

步骤 3：设置应用程序 ID URI

  1. 导航到“公开 API”：

    • 在应用的菜单中，选择“公开 API”
    • 在 "应用程序 ID URI" 旁边，选择添加

  2. 创建唯一 URI：

    api://localdevinstance/[YOUR-TENANT-ID]/[YOUR-WORKLOAD-NAME]/[RANDOM-STRING]

    示例： api://localdevinstance/aaaabbbb-0000-cccc-1111-dddd2222eeee/Org.MyWorkload/AbCdE

步骤 4：配置 API 权限

  1. 添加所需的权限：

    • 转到 API 权限
    • 选择“添加权限”

  2. 添加 Microsoft Fabric 权限：

    • 选择 组织使用的 API
    • 搜索“Power BI 服务”（应用 ID： 00000009-0000-0000-c000-000000000000）
    • 选择 “委派权限 ”并添加：
      • Fabric.Extend
      • Workspace.Read.All
      • Item.Execute.All
      • Item.Read.All
      • Item.ReadWrite.All
      • Item.Reshare.All
      • Lakehouse.Read.All
      • Eventhouse.Read.All
      • KQLDatabase.ReadWrite.All

  3. 添加 Azure 存储权限：

    • 添加“Azure 存储”的权限（应用 ID： e406a681-f3d4-42a8-90b6-c2b029497af1）
    • 选择 user_impersonation

  4. 添加Microsoft图形权限：

    • 添加“Microsoft Graph”的权限
    • 选择 User.Read

  5. 添加 Azure 数据资源管理器权限：

    • 添加“Azure 数据资源管理器”的权限（应用 ID： 00001111-aaaa-2222-bbbb-3333cccc4444）
    • 选择 user_impersonation

步骤 5：创建 OAuth 作用域（用于远程托管）

如果工作负荷使用远程托管，请添加自定义范围：

  1. 导航到“公开 API”

  2. 添加范围：

    • 选择“添加范围”
    • 对于每个范围，请提供：
      • 范围名称：例如 FabricWorkloadControl
      • 管理员同意显示名称：描述性名称
      • 管理员许可说明：范围允许的内容
      • 状态：已启用

  3. 所需范围：

    • FabricWorkloadControl
    • Item1.Read.All
    • Item1.ReadWrite.All
    • FabricLakehouse.Read.All
    • FabricLakehouse.ReadWrite.All
    • KQLDatabase.ReadWrite.All
    • FabricEventhouse.Read.All

步骤 6：配置预授权的应用程序

  1. 添加授权客户端应用程序：

    • 在“公开 API”中，选择“添加客户端应用程序”
    • 添加以下具有适当作用域的应用程序 ID：

  2. Microsoft Fabric 应用程序：

    871c010f-5e61-4fb1-83ac-98610a7e9110 (Fabric client app)
00000009-0000-0000-c000-000000000000 (Power BI Service)
d2450708-699c-41e3-8077-b0c8341509aa (Additional Fabric app)

步骤 7：创建客户端密码

  1. 生成机密：
    • 转到 证书和机密
    • 选择 “新建客户端密码”
    • 提供开发过程的说明，并设置到期时间（建议 180 天）。
    • 立即复制机密值（不会再次显示）

  1. 同意权限：

    • 在 API 权限中， 为 [组织] 选择“授予管理员同意”
    • 确认同意

  2. 备用许可 URL：还可以使用此直接 URL（在创建应用后等待一分钟）：

    https://login.microsoftonline.com/[YOUR-TENANT-ID]/adminconsent?client_id=[YOUR-APP-ID]

后续步骤

创建Microsoft Entra 应用后：

  1. 更新环境配置：

    • 复制应用程序 ID、机密和其他值
    • 使用这些值更新您的.env文件
    • 请参阅环境配置的设置指南

  2. 测试身份验证：

    • 在本地运行工作负载
    • 验证身份验证是否正常工作
    • 检查 API 调用是否成功

  3. 配置其他设置：

    • 根据需要查看和调整令牌生存期
    • 为不同环境添加其他重定向 URI
    • 根据需要配置可选声明

Troubleshooting

常见问题

“重定向 URI 无效”

  • 确保重定向 URI 与配置的值完全匹配
  • 检查尾部斜杠或拼写错误
  • 验证协议（http 与 https）

“权限不足”

  • 确保拥有应用程序管理员或全局管理员权限
  • 某些权限需要管理员同意

“受众无效”

  • 验证应用程序 ID URI 是否遵循正确的模式
  • 检查租户 ID 和工作负荷名称是否正确

“权限被拒绝”

  • 确保已授予管理员同意
  • 检查是否添加了所需的权限
  • 验证用户是否有权访问工作区

获取帮助

如果遇到问题：

  1. 检查应用程序概述：查看所有配置的设置
  2. 验证权限：确保存在和同意所有必需的权限
  3. 查看日志：检查Microsoft Entra ID 登录日志以获取详细的错误信息
  4. 使用 Graph 资源管理器进行测试：使用 Microsoft Graph 资源管理器验证权限

安全最佳做法

  • 定期轮换机密：设置进程以在过期前轮换客户端机密
  • 使用最短的必要权限：仅授予工作负荷实际需要的权限
  • 监视使用情况：定期查看登录日志和 API 使用情况
  • 安全机密存储：从不将机密提交到源代码;使用安全配置管理
  • Last updated on