使用服务主体和应用程序机密嵌入 Power BI 内容

服务主体是一种身份验证方法，可用于让 Microsoft Entra 应用程序访问 Power BI 服务内容和 API。

创建 Microsoft Entra 应用时，将创建服务主体对象。 借助服务主体对象（也称为服务主体），Microsoft Entra ID 可以对应用进行身份验证。 对应用进行身份验证后，该应用即可访问 Microsoft Entra 租户资源。

为了进行身份验证，服务主体将使用 Microsoft Entra 应用的应用程序 ID 以及下列项之一：

• 一个证书
• 应用程序机密

本文介绍如何使用应用程序 ID 和应用程序机密进行服务主体身份验证。

注意

建议使用证书而不是密钥来保护后端服务。

• 详细了解如何使用机密密钥或证书从 Microsoft Entra ID 获取访问令牌。
• 若要使用证书保护解决方案，请完成本文中的说明，然后按照使用服务主体和证书嵌入 Power BI 内容中所述的步骤进行操作。

方法

若要使用服务主体和应用程序 ID 进行嵌入式分析，请执行以下步骤。 后续部分详细介绍了这些步骤。

1. 创建一个 Microsoft Entra 应用。

   1. 为 Microsoft Entra 应用创建机密。
   2. 获取应用的应用程序 ID 和应用程序机密。

   注意

   “第 1 步”中介绍了这些步骤。 有关创建 Microsoft Entra 应用的详细信息，请参阅创建 Microsoft Entra 应用。

2. 创建 Microsoft Entra 安全组。

3. 启用 Power BI 服务管理设置。

4. 将服务主体添加到工作区中。

5. 嵌入内容。

重要

在为服务主体创建 Microsoft Entra 应用程序后，无需在 Azure 门户中为该应用程序配置任何委派权限或应用程序权限。 为服务主体创建 Microsoft Entra 应用程序以访问 Power BI REST API 时，建议避免添加权限。 它们永远不会被使用，并且可能导致难以排查的错误。

步骤 1 - 创建 Microsoft Entra 应用

使用以下方法之一创建 Microsoft Entra 应用：

• 在 Azure 门户中创建应用。
• 使用 PowerShell 创建应用。

在 Azure 门户中创建 Microsoft Entra 应用

1. 登录 Azure 门户。

2. 搜索并选择“应用注册”。

   

3. 选择“新注册”。

   

4. 填写所需信息：

   • 名称 - 输入应用程序名称。
   • 支持的帐户类型 - 选择支持的帐户类型。
   • （可选）重定向 URI - 视需要输入 URI。

5. 选择“注册”。

6. 注册应用后，可以从“概览”选项卡中获取“应用程序 ID”。复制并保存“应用程序 ID”，以供稍后使用。

   

7. 选择“证书和机密”。

   

8. 选择“新建客户端机密”。

   

9. 在“添加客户端密码”窗口中，输入描述，指定所需的客户端密码到期时间，然后选择“添加”。

10. 复制并保存客户端密码值。

    

    注意

    在离开此窗口后，客户端密码值将隐藏，你将无法再次查看或复制它。

使用 PowerShell 创建 Microsoft Entra 应用

以下示例 PowerShell 脚本创建新的 Microsoft Entra 应用和服务主体。 开始运行此脚本之前：

• 安装最新版本的 PowerShell。
• 安装 Microsoft Graph PowerShell SDK。

脚本运行后，在脚本输出中记下以下信息：

• 新应用的客户端 ID
• 新服务主体的对象 ID
• 服务主体机密的值

# Sign in as a user who's allowed to create an app.
Connect-MgGraph -Scopes "Application.ReadWrite.All" 

# Create a new Azure AD web application.
$web = @{
    RedirectUris = "https://localhost:44322"
    HomePageUrl = "https://localhost:44322"
}
$params = @{
    DisplayName = "myAzureADApp"
    Web = $($web)
}
$app = New-MgApplication @params
Write-Host "Client ID of new app: " $($app.AppId)

# Create a service principal.
$ServicePrincipalID=@{
  "AppId" = $($app.AppId)
  }
$sp = New-MgServicePrincipal -BodyParameter $($ServicePrincipalId)
Write-Host "Object ID of new service principal: " $($sp.Id)

# Create a key for the service principal.
$credential = Add-MgServicePrincipalPassword -ServicePrincipalId $($sp.Id)
Write-Host "Credential of new service principal: " $($credential.SecretText)

步骤 2 - 创建 Microsoft Entra 安全组

服务主体无权访问你的任何 Power BI 内容和 API。 要授予服务主体访问权限，请在 Microsoft Entra ID 中创建安全组。 然后将创建的服务主体添加到该安全组。

注意

若要为整个组织启用服务主体访问权限，请跳过这一步。

可通过两种方式创建 Microsoft Entra 安全组：

• 手动（在 Azure 中）
• 使用 PowerShell

手动创建安全组

若要手动创建 Azure 安全组，请按照创建基本组并添加成员一文中的说明操作。

使用 PowerShell 创建安全组

以下示例脚本创建新的安全组。 它还将前面创建的服务主体添加到新安全组。

• 运行脚本之前，请将 <app-client-ID> 替换为前面为新应用记录的客户端 ID。
• 运行脚本后，记下新安全组的对象 ID，可以在脚本输出中找到该 ID。

# Sign in as an admin.
Connect-MgGraph -Scopes "Application.ReadWrite.All"

# Get the service principal that you created earlier.
$servicePrincipal = Get-MgServicePrincipal -Filter "AppId eq '<app-client-ID>'"

# Create an Azure AD security group.
$group = New-MgGroup -DisplayName "securitygroup1" -SecurityEnabled -MailEnabled:$False -MailNickName "notSet"
Write-Host "Object ID of new security group: " $($group.Id)

# Add the service principal to the group.
New-MgGroupMember -GroupId $($group.Id) -DirectoryObjectId $($servicePrincipal.Id)

第 3 步 - 启用 Power BI 服务管理设置

为了让 Microsoft Entra 应用访问 Power BI 内容和 API，Power BI 管理员需要启用以下设置：

• 在应用中嵌入内容
• 允许服务主体使用 Power BI API

在 Power BI 管理员门户中，转到“租户设置”，然后向下滚动到“开发人员设置”。

• 为整个组织或在 Microsoft Entra ID 中创建的特定安全组启用“在应用中嵌入内容”。

  

• 为整个组织或在 Microsoft Entra ID 中创建的特定安全组启用“允许服务主体使用 Power BI API”。

  

  重要

  服务主体有权访问为其启用的任何租户设置。 这包括特定安全组或整个组织，具体视管理设置而定。

  若要限制服务主体只能访问特定租户设置，请只允许访问特定安全组。 也可以为服务主体创建专用安全组，并将它排除在相应租户设置之外。

第 4 步 - 将服务主体添加到工作区

仅当 Microsoft Entra 应用有权访问 Power BI 工作区时，才能访问 Power BI 报表、仪表板和语义模型。 可以通过将应用的服务主体或其安全组作为成员或管理员添加到工作区来提供该访问权限。

可通过三种方法将服务主体或其安全组添加到工作区：

• 手动
• 使用 PowerShell
• 使用组 - 添加组用户 API

手动添加服务主体或安全组

1. 在 Power BI 服务中，滚动到要为其启用访问权限的工作区。 在“更多”菜单中，选择“工作区访问权限”。

   

2. 在“访问”窗格的“添加管理员、成员或参与者”下，添加以下项之一：

   • 你的“服务主体”。 服务主体的名称是 Microsoft Entra 应用的显示名称，如 Microsoft Entra 应用的概述选项卡中所示。
   • 包含服务主体的“安全组”。

3. 在下拉菜单上选择“成员”或“管理员”。

4. 选择 添加 。

使用 PowerShell 添加服务主体或安全组

以下部分提供了示例 PowerShell 脚本，用于将服务主体和安全组作为成员添加到 Power BI 工作区。

使用 PowerShell 将服务主体添加为工作区成员

以下脚本将服务主体添加为工作区成员。 运行脚本之前：

• 将 <service-principal-object-ID> 替换为前面为新服务主体记录的对象 ID。
• 将 <workspace-name> 替换为要授予服务主体访问权限的工作区的名称。

# Sign in to Power BI.
Login-PowerBI

# Set up the service principal ID.
$SPObjectID = "<service-principal-object-ID>"

# Get the workspace.
$pbiWorkspace = Get-PowerBIWorkspace -Filter "name eq '<workspace-name>'"

# Add the service principal to the workspace.
Add-PowerBIWorkspaceUser -Id $($pbiWorkspace.Id) -AccessRight Member -PrincipalType App -Identifier $($SPObjectID)

使用 PowerShell 将安全组添加为工作区成员

以下脚本将安全组添加为工作区成员。 运行脚本之前：

• 将 <security-group-object-ID> 替换为前面为新安全组记录的对象 ID。
• 将 <workspace-name> 替换为要授予安全组访问权限的工作区的名称。

# Sign in to Power BI.
Login-PowerBI

# Set up the security group object ID.
$SGObjectID = "<security-group-object-ID>"

# Get the workspace.
$pbiWorkspace = Get-PowerBIWorkspace -Filter "name eq '<workspace-name>'"

# Add the security group to the workspace.
Add-PowerBIWorkspaceUser -Id $($pbiWorkspace.Id) -AccessRight Member -PrincipalType Group -Identifier $($SGObjectID)

第 5 步 - 嵌入内容

可以在示例应用程序或你自己的应用程序中嵌入内容。

嵌入内容后，便可以迁移到生产阶段。

注意

若要使用证书保护内容，请按照使用服务主体和证书嵌入 Power BI 内容中所述的步骤进行操作。

注意事项和限制

• 使用服务主体时，不支持“我的工作区”。
• 移动到生产环境时，需要容量。
• 无法使用服务主体登录 Power BI 门户。
• 在 Power BI 管理门户的开发人员设置中启用服务主体需要 Power BI 管理权限。
• 无法使用服务主体为组织应用程序嵌入内容。
• 不支持数据流管理。
• 服务主体仅支持某些只读管理 API。 若要为只读管理 API 启用服务主体支持，必须在租户中启用 Power BI 服务管理设置。 有关详细信息，请参阅为只读管理 API 启用服务主体身份验证。
• 使用带有 Azure Analysis Services 数据源的服务主体时，服务主体本身必须具有 Azure Analysis Services 实例权限。 使用包含服务主体的安全组来实现此目的，这不起作用。

相关内容

• 注册应用
• 适用于客户的 Power BI Embedded
• Microsoft Entra ID 中的应用程序和服务主体对象