Fabric 应用的身份验证

Fabric应用包括一种内置身份验证服务，用于让用户登录、管理会话，并将其标识附加到应用发出的每个数据和存储调用。 本文介绍在为项目配置身份验证之前需要了解的概念。

有关实现详细信息，请参阅：

身份验证模式

部署的 Fabric 应用使用 Microsoft Entra ID 进行认证。 根据应用运行的位置和获取 Entra 令牌的一方选择集成路径：

环境 支持的方法 何时使用它
使用Fabric门户的浏览器应用 Fabric SSO 弹窗或嵌入式交接 让 Fabric 进行交互式登录，或者在嵌入在 Fabric 中的应用中登录。
浏览器或 Node.js 应用，已具有委托的 Entra 令牌 signInWithEntraToken() 使用提供的令牌换取一个 Rayfin 会话，无需弹窗或重定向。
嵌入外部父级门户中的应用 createEmbedHost() 在父端和 initEmbeddedAuth() 在 iframe 中 让一个受信任的 Entra 认证父节点在不将其令牌发送给 iframe 的情况下协调一次交接。
本地开发与本地后端 电子邮件和密码 测试时针对本地后端;这种方法在已部署的 Fabric 后端上不起作用。

关键概念：

  • Fabric SSO 使用 Fabric 门户来认证浏览器用户。 该应用可以在 Fabric 内部运行，也可以使用独立页面的弹窗，也包括连接已部署后端的本地前端方案。
  • 直接 Entra 交换和外部父主机移交流程是 Microsoft Entra 的额外路径，不支持任意身份提供者或仅应用服务主体登录。
  • 电子邮件和密码 仅适用于本地开发。 部署后它不起作用。
  • 首次登录时会为用户完成预配。 使用 Fabric SSO 时，没有单独的注册步骤 - 用户首次登录时会自动创建。
  • Fabric部署需要身份验证。 将services.auth.enabled设置为false会导致npx rayfin up失败。

有关令牌需求和实现示例，请参见 直接Entra令牌登录 和 嵌入外部父级门户。

会话和标识

用户登录后，SDK 将创建表示已登录用户的 会话 。 会话是不透明的——你的应用不应检查底层令牌。 而是，你的应用会读取一组少量的高层属性：

  • 会话当前是否经过身份验证。
  • 用户的 id 和 email。
  • 您在 rayfin.yml 中配置的自定义声明。

对用户进行签名的同一客户端实例会自动将其标识附加到每个数据和存储调用。 不会手动传递令牌。

会话还会引发更改事件，因此当用户登录或注销时 UI 可以做出反应，而无需重新加载页面。

对于服务器端集成，每个用户使用单独的客户端和仅内存 Auth 会话（authStorage: false 在 RayfinClient 上，或 { storage: false } 在 Auth 上）。 切勿在不同用户之间共享可变的已登录客户端。 当认证实例的请求或用户特定作用域结束时，销毁该实例。

在项目中启用身份验证

身份验证在 rayfin/rayfin.yml 中配置。 以下示例启用 Fabric SSO（适用于已部署的应用）和电子邮件/密码登录（用于本地开发）：

services:
  auth:
    enabled: true
    allowedRedirectUris:
      - http://localhost:5173
    fabric:
      enabled: true
      externalEntraExchange: true
    password:
      enabled: true  # Local development only

每个设置控制的内容：

  • services.auth.enabled – 打开身份验证服务。 这是任何 Fabric 部署所必需的。
  • allowedRedirectUris – 登录后允许接收用户的源。 在此处添加本地开发 URL。 npx rayfin up 自动添加已部署的应用源。
  • fabric.enabled – 启用Fabric SSO。 已部署的应用必需此项。
  • fabric.externalEntraExchange – 支持直接委托的 Entra 令牌交换和外部父主机移交。 目标 Fabric 环境也必须支持该 Exchange。
  • password.enabled – 启用用于本地开发的电子邮件和密码登录。

Important

Fabric部署需要启用身份验证。 当 npx rayfin up 设置为 services.auth.enabled 时，false 失败。

编辑 rayfin.yml后，重启本地后端或运行 npx rayfin up 以应用更改。

外部获取的 Entra 令牌的先决条件

直接交换和 external-parent-host 身份验证需要目标部署接受的、面向 Fabric/Power BI 受众的委托用户令牌，并带有 Item.Execute.All，该令牌在该项目所属租户中签发。 用户还必须对应用项目拥有 执行 权限。 这些登录路径不支持仅限应用的令牌。

你的身份库负责获取令牌并处理用户授权同意。 Rayfin SDK 用它交换 Rayfin 会话;它不会获得 Entra 令牌。 浏览器调用者还需要服务的 CORS 策略来允许源和授权头。

自定义声明

使用自定义声明可将特定于应用程序的元数据附加到每个会话，例如租户名称、功能标志或应用版本。 它们可用于基于角色的访问控制和功能限制，而无需更改数据模型。

services:
  auth:
    enabled: true
    customClaims:
      tenant: default
      app_version: 1.0.0

自定义声明显示在会话对象内，可以从数据权限规则中引用。

SDK 提供的内容

使用 RayfinClient 时，身份验证服务可在 client.auth 上使用。 在概念级别，它提供：

  • 在本地开发期间，使用电子邮件和密码注册和登录。
  • 通过 Fabric SSO 登录和注册已部署的应用。 同一调用同时处理新用户和返回用户。
  • 通过浏览器或 Node.js 代码直接委派 Entra 令牌交换，以及用于嵌入式应用的可信外部父主机交接。
  • 注销 以结束当前会话。
  • 会话读取和订阅 ，以便 UI 与用户的身份验证状态保持同步。

关于将这些功能接入真实应用的代码，请参见“为您的Fabric应用配置Fabric SSO认证”。 有关回调和交接允许列表的指导，请参见 配置身份验证重定向 URI。

相关内容

  • 上次更新时间为