Microsoft Fabric 扩展性工具包的身份验证指南

本文提供了有关如何在生成 Microsoft Fabric 扩展性工具包工作负载时使用身份验证的指南。 它包括有关使用令牌、同意以及从前端应用程序访问各种服务的信息。

在开始之前，请确保熟悉 身份验证概述中的概念。

仅限前端的身份验证模型

扩展性工具包使用仅限前端的体系结构，与传统工作负载相比，它简化了身份验证：

• 直接 API 调用：前端直接调用 Fabric API、Azure 服务和外部应用程序
• 令牌重用：单个令牌可用于对多个受 Entra 保护的服务进行身份验证
• 简化同意：许可管理由平台使用自动提示进行处理

Microsoft Entra 应用程序配置

公开 API 选项卡

为您的负载应用程序配置权限范围：

• Fabric 集成范围：使用应用程序 ID 预先授权 Microsoft Power BI871c010f-5e61-4fb1-83ac-98610a7e9110
• 自定义 API 范围：为工作负载公开的任何自定义 API 添加作用域
• 精细权限：针对读取和写入操作采用不同的范围

例如，如果你的工作负载（workload）公开数据 API：

• 添加 data.read 读取操作的范围
• 添加 data.write 写操作的范围
• 在 API 处理程序中验证适当的权限范围

“API 权限”选项卡

为工作负荷需要访问的外部服务配置权限：

• 必需： Fabric.Extend 在 Power BI 服务下（Fabric 集成必需）
• Azure 服务：添加 Azure 服务的范围，例如 https://storage.azure.com/user_impersonation
• 自定义应用程序：为自己的受 Entra 保护的应用程序添加作用域
• 第三方服务：包括支持 Entra 身份验证的任何外部服务

令牌使用模式

对多个服务使用令牌

通过 Extensibility Toolkit 获取的前端令牌可用于针对以下情况进行身份验证：

Fabric 应用程序接口

// Token automatically includes required Fabric scopes
const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Azure 服务

// Same token works for Azure services
const response = await fetch('https://management.azure.com/subscriptions', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

自定义应用程序

// Token works for your own Entra-secured applications
const response = await fetch('https://myapp.contoso.com/api/data', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

范围管理

用于常见场景的扩展工具包简化了范围管理：

• Fabric 客户端库：自动包括所需的 Fabric 范围
• Azure 客户端库：以透明方式处理 Azure 服务范围
• 自定义范围：根据需要指定其他作用域

使用许可

初始令牌获取

首先获取令牌以建立身份验证上下文：

const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });

此调用可能会导致：

• 同意提示：如果用户尚未同意应用程序
• 无提示获取：如果之前已授予同意

处理附加服务访问

当工作负荷需要访问其他服务时，请指定所需的范围：

try {
  // Request token with specific scopes for Azure Storage
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://storage.azure.com/user_impersonation']
  });
  
  // Use token to access Azure Storage
  const response = await fetch('https://mystorageaccount.blob.core.windows.net/', {
    headers: { 'Authorization': `Bearer ${token.token}` }
  });
} catch (error) {
  // Handle authentication or authorization errors
  console.error('Access failed:', error.message);
}

示例方案

方案 1：访问 Fabric 和 Azure 服务

您的工作负载应当：

• 列出 Fabric 工作区
• 从 Azure 存储读取
• 写入 Azure Key Vault

实现：

1. 为所需服务配置 API 权限
2. 获取初始令牌
3. 对所有服务调用使用令牌
4. 根据需要处理同意提示

方案 2：自定义应用程序集成

您的工作负载与您自己的后端服务集成：

1. 配置后端：确保后端系统能够接受 Entra 令牌
2. 添加 API 权限：在工作负荷应用程序中包括后端的范围
3. 使用标准身份验证：相同的令牌模式适用于自定义服务

方案 3：第三方服务集成

与支持 Entra 的外部服务集成：

1. 服务注册：将工作负荷注册到第三方服务
2. 范围配置：将服务的作用域添加到 API 权限
3. 令牌用法：对外部服务使用相同的身份验证模式

错误处理和故障排除

常见身份验证错误

• 需要许可：用户未授予特定范围的权限
• 条件访问：其他身份验证要求（例如 MFA）
• 令牌过期：令牌已过期，需要刷新
• 无效的范围：未配置或可用请求的范围

错误处理模式

async function handleAuthenticatedRequest(url: string, requiredScopes: string[] = []) {
  try {
    const token = await workloadClient.auth.acquireFrontendAccessToken({ 
      scopes: requiredScopes 
    });
    return await makeRequest(url, token);
  } catch (error) {
    if (error.code === 'consent_required') {
      // User needs to grant consent for the requested scopes
      console.error('Consent required for scopes:', requiredScopes);
    }
    throw error;
  }
}

重定向 URI 处理

扩展性工具包包括用于身份验证同意弹窗的内置重定向 URI 处理机制。 这在主 index.ts 文件中实现，并自动处理同意重定向。

工具包处理：

• 自动关闭窗口：同意弹出窗口在用户交互后自动关闭
• 错误处理：检测到并适当处理特定的错误代码
• 错误显示：失败的许可尝试显示用户友好的错误消息

工具包中的当前实现：

const redirectUriPath = '/close';
const url = new URL(window.location.href);
if (url.pathname?.startsWith(redirectUriPath)) {
  // Handle errors
  if (url?.hash?.includes("error")) {
    if (url.hash.includes("AADSTS650052")) {
      // Handle missing service principal error
      printFormattedAADErrorMessage(url?.hash);
    } else if (url.hash.includes("AADSTS65004")) {
      // Handle user declined consent error
      printFormattedAADErrorMessage(url?.hash);
    } else {
      window.close();
    }
  } else {
    // Close window on successful consent
    window.close();
  }
}

最佳做法

令牌管理

• 缓存令牌：重复使用令牌，直到令牌过期
• 处理刷新：实现自动令牌刷新逻辑
• 安全存储：在浏览器内存中安全地存储令牌

同意管理

• 最小权限：仅请求实际需要的范围
• 渐进式同意：使用功能时请求其他权限
• 清除消息：向用户解释为什么需要权限

错误处理

• 正常降级：尽可能提供回退功能
• 用户反馈：明确传达身份验证要求
• 重试逻辑：为瞬态故障实现适当的重试机制

相关内容

• 身份验证概述
• 身份验证 JavaScript API