Power BI 的服务主体Service principal with Power BI

使用服务主体,可将 Power BI 内容嵌入应用程序,并通过仅限应用的令牌在 Power BI 中使用自动化 。With service principal, you can embed Power BI content into an application and use automation with Power BI using an app-only token. 使用 Power BI Premium Embedded 或自动处理 Power BI 任务和进程时,服务主体特别有用 。Service principal is beneficial when using Power BI Embedded or when automating Power BI tasks and processes.

使用 Power BI Embedded 时,使用服务主体具有优势。When working with Power BI Embedded, there are advantages when using service principal. 主要优势是不需要主帐户(仅包含登录用户名和密码的 Power BI Pro 许可证)即可对应用程序进行身份验证。A primary advantage is you don't need a master account (Power BI Pro license that is merely a username and password to sign in) to authenticate into your application. 服务主体使用应用程序 ID 和应用程序密码对应用程序进行身份验证。Service principal uses an application ID and an application secret to authenticate the application.

努力自动处理 Power BI 任务时,还可编写如何处理和管理服务主体以进行缩放的脚本。When working to automate Power BI tasks, you can also script how to process and manage service principals to scale.

应用程序和服务主体的关系Application and service principal relationship

为了访问用于保护 Azure AD 租户的资源,需要访问权限的实体应表示安全主体。To access resources that secure an Azure AD tenant, the entity that requires access represents a security principal. 此操作同时适用于用户(用户主体)和应用程序(服务主体)。This action holds true for both users (user principal) and applications (service principal).

安全主体定义适用于 Azure AD 租户中的用户和应用程序的访问策略和权限。The security principal defines the access policy and permissions for users and applications in the Azure AD tenant. 此访问策略支持核心功能(例如,登录期间的用户和应用程序身份验证和资源访问期间的授权)。This access policy enables core features such as authentication of users and applications during sign-in, and authorization during resource access. 有关详细信息,请参考 Azure Active Directory (AAD) 中的应用程序和服务主体For more information, reference Application and service principal in Azure Active Directory (AAD).

在 Azure 门户中注册 Azure AD 应用程序时,Azure AD 租户中将创建两个对象:When you register an Azure AD application in the Azure portal, two objects are created in your Azure AD tenant:

将应用程序对象视为应用程序的全局表示形式以用于所有租户,将服务主体对象视为本地本地表示形式以用于特定租户 。Consider the application object as the global representation of your application for use across all tenants, and the service principal object as the local representation for use in a specific tenant.

应用程序对象可充当派生常见和默认属性的模板,以用于创建对应的服务主体对象 。The application object serves as the template from which common and default properties are derived for use in creating corresponding service principal objects.

每个使用应用程序的租户都需要服务主体 - 因此,它可以生成标识,以用于登录和访问受租户保护的资源。A service principal is required per tenant where the application is used — enabling it to establish an identity for sign-in and access to resources that are secured by the tenant. 单租户应用程序仅创建一个服务主体(在其主租户中)并允许在应用程序注册期间使用该服务主体。A single-tenant application has only one service principal (in its home tenant), created and consented for use during application registration.

Power BI Embedded 的服务主体Service principal with Power BI Embedded

凭借服务主体,可以使用应用程序 ID 和应用程序密码屏蔽应用程序中的主帐户信息。With service principal, you can mask your master account information in your application by using an application ID and an application secret. 无需再将主帐户硬编码到应用程序中也可进行身份验证。You no longer need to hard-code a master account into your application to authenticate.

由于 Power BI API 和 Power BI .NET SDK 现支持使用服务主体调用,因此可以将 Power BI REST API 与服务主体配合使用 。Since Power BI APIs and Power BI .NET SDK now support calls using service principal, you can use the Power BI REST APIs with service principal. 例如,可以更改工作区,例如,创建工作区、添加或删除工作区中的用户,并将内容导入工作区。For example, you can make changes to workspaces such as create workspaces, add or remove users from workspaces, and import content into workspaces.

如果 Power BI 项目和资源存储于新的 Power BI 工作区,则只能使用服务主体。You can only use service principal if your Power BI artifacts and resources are stored in the new Power BI workspace.

服务主体与主帐户Service principal vs. master account

使用服务主体和标准主帐户(Power BI Pro 许可证)进行身份验证之间存在差异。There are differences between using a service principal and a standard master account (Power BI Pro license) for authentication. 下表突出显示部分显著差异。The below table highlights some significant differences.

函数Function 主用户帐户Master User Account
(Power BI Pro 许可证)(Power BI Pro license)
服务主体Service Principal
(仅限应用的令牌)(app-only token)
可以登录 Power BI 服务Can sign in to the Power BI service Yes No
在 Power BI 管理门户中启用Enabled in the Power BI Admin portal No Yes
用于应用工作区 (v1)Works with app workspaces (v1) Yes No
用于新的应用工作区 (v2)Works with the new app workspaces (v2) Yes Yes
如果与 Power BI Embedded 配合使用,则需要是工作区管理员Needs to be a workspace admin if used with Power BI Embedded Yes Yes
可以使用 Power BI REST APICan use Power BI REST APIs Yes Yes
需要全局管理员才能创建Needs a global admin to create Yes No
可以安装和管理本地数据网关Can install and manage an On-premises data gateway Yes No

开始使用服务主体Get started with a service principal

不同于主帐户的传统用法,使用服务主体(仅限应用的令牌)需要几个不同的部分才能设置。Different from the traditional use of a master account, using the service principal (app-only token) requires a few different pieces to set up. 要开始使用服务主体(仅限应用的令牌),则需要设置适当的环境。To get started with service principal (app-only token), you need to set up the right environment.

  1. 在 Azure Active Directory (AAD) 中注册服务器端 Web 应用程序,以便与 Power BI 配合使用。Register a server-side web application in Azure Active Directory (AAD) to use with Power BI. 注册应用程序之后,可以捕获应用程序 ID、应用程序密码和服务主体对象 ID 以访问 Power BI 内容。After registering an application you can capture an application ID, an application secret, and the service principal object ID to access your Power BI content. 可以使用 PowerShell 创建服务主体。You can create a service principal with PowerShell.

    下面是创建新的 Azure Active Directory 应用程序的示例脚本。Below is a sample script to create a new Azure Active Directory application.

    # The app id - $app.appid
    # The service principal object id - $sp.objectId
    # The app key - $key.value
    
    # Sign in as a user that is allowed to create an app.
    Connect-AzureAD
    
    # Create a new AAD web application
    $app = New-AzureADApplication -DisplayName "testApp1" -Homepage "https://localhost:44322" -ReplyUrls "https://localhost:44322"
    
    # Creates a service principal
    $sp = New-AzureADServicePrincipal -AppId $app.AppId
    
    # Get the service principal key.
    $key = New-AzureADServicePrincipalPasswordCredential -ObjectId $sp.ObjectId
    

    重要

    在使服务主体可用于 Power BI 后,应用程序的 AD 权限将不再有效。Once you enable service principal to be used with Power BI, the application's AD permissions don't take effect anymore. 然后,将通过 Power BI 管理门户管理应用程序权限。The application's permissions are then managed through the Power BI admin portal.

  2. 建议 - 在 Azure Active Directory (AAD) 中创建安全组,并将所创建的应用程序添加到该安全组。Recommended - Create a security group in Azure Active Directory (AAD), and add the application you created to that security group. 可以使用 PowerShell 创建 AAD 安全组。You can create an AAD security group with PowerShell.

    下面的示例脚本可用于创建新安全组并向该安全组添加应用程序。Below is a sample script to create a new security group and add an application to that security group.

    # Required to sign in as a tenant admin
    Connect-AzureAD
    
    # Create an AAD security group
    $group = New-AzureADGroup -DisplayName <Group display name> -SecurityEnabled $true -MailEnabled $false -MailNickName notSet
    
    # Add the service principal to the group
    Add-AzureADGroupMember -ObjectId $($group.ObjectId) -RefObjectId $($sp.ObjectId)
    
  3. Power BI 管理员需要启用 Power BI 管理门户中“开发人员设置”中的服务主体 。As a Power BI admin, you need to enable service principal in the Developer settings in the Power BI admin portal. 将 Azure AD 中创建的安全组添加到“开发人员设置”中的特定安全组部分 。Add the security group that you created in Azure AD to the specific security group section in the Developer settings. 还可以为整个组织启用服务主体访问。You can also enable service principal access for the entire organization. 在这种情况下,无需执行步骤 2。In that case, step 2 is not needed.

    重要

    服务主体有权访问为整个组织启用的或者为包含服务主体的安全组启用的所有租户设置。Service principals have access to any tenant settings that are enabled for the entire organization or enabled for security groups that have service principals as a part of the group. 要限制服务主体访问特定租户设置,请只允许访问特定安全组,或者为服务主体创建一个专用安全组并将其排除在外。To restrict service principal access to specific tenant settings, allow access only to specific security groups, or create a dedicated security group for service principals and exclude it.

    管理门户

  4. 设置 Power BI 环境Set up your Power BI environment.

  5. 以管理员身份将服务主体添加到创建的新工作区 。Add the service principal as an admin to the new workspace you created. 可以通过 API 或使用 Power BI 服务管理此任务。You can manage this task through the APIs or with the Power BI service.

    以管理员身份将服务主体添加到工作区

  6. 现在选择在示例应用程序或自己的应用程序中嵌入内容。Now choose to embed your content within a sample application, or within your own application.

  7. 现在,你已准备好移动到生产环境Now you're ready to move to production.

改为使用服务主体Migrate to service principal

如果目前正在使用 Power BI 或 Power BI Embedded 的主帐户,则可改为使用服务主体。You can migrate to use service principal if you're currently using a master account with Power BI or with Power BI Embedded.

完成开始使用服务主体部分中的前三个步骤,在完成后,按照以下说明操作。Complete the first three steps in section Get started with a service principal, and once complete, follow the information below.

如果已使用 Power BI 中的新工作区,则以管理员身份使用 Power BI 项目将服务主体添加到该工作区 。If you're already using the new workspaces in Power BI, then add the service principal as an admin to the workspaces with your Power BI artifacts. 但如果使用传统工作区,则将 Power BI 项目和资源复制并迁移到新工作区,然后以管理员身份将服务主体添加到这些工作区 。However, if you're using the traditional workspaces, copy or move your Power BI artifacts and resources into the new workspaces, and then add the service principal as an admin to those workspaces.

没有用于将 Power BI 项目和资源从一个工作区移到另一个工作区的 UI 功能,因此需要使用 API 才能完成此任务。There's no UI feature to move Power BI artifacts and resources from one workspace to another, so you need to use APIs to accomplish this task. 将 API 与服务主体配合使用时,需要使用服务主体对象 ID。When using the APIs with service principal, you need the service principal object ID.

如何获取服务主体对象 IDHow to get the service principal object ID

要将服务主体分配到新的应用工作区,请使用 Power BI REST APITo assign a service principal to a new app workspace, you use the Power BI REST APIs. 若要引用服务主体用于操作或进行更改,请使用服务主体对象 ID - 例如,以管理员身份将服务主体应用于工作区 。To reference a service principal for operations or to make changes you use the service principal object ID — for example, applying a service principal as an admin to a workspace.

下面是从 Azure 门户获取服务主体对象 ID 的步骤。Below are steps to get the service principal object ID from the Azure portal.

  1. 在 Azure 门户中创建新的应用注册。Create a new App registration in the Azure portal.

  2. 然后在“本地目录中的托管应用程序”下,选择创建的应用程序的名称 。Then under Managed application in local directory, select the name of the application you created.

    本地目录中的托管应用程序

    备注

    上图中的对象 ID 不是用于服务主体的对象 ID。The object Id in the image above is not the one used with service principal.

  3. 选择“属性”查看对象 ID 。Select Properties to see the Object ID.

    服务主体对象 ID 属性

以下是使用 PowerShell 检索服务主体对象 ID 的示例脚本。Below is a sample script to retrieve the service principal object ID with PowerShell.

Get-AzureADServicePrincipal -Filter "DisplayName eq '<application name>'"

注意事项和限制Considerations and limitations

  • 服务主体仅适用于新的应用工作区Service principal only works with new app workspaces.
  • 使用服务主体时,不支持“我的工作区” 。My Workspace isn't supported when using service principal.
  • 移动到生产环境时,需要专用容量。Dedicated capacity is required when moving to production.
  • 无法使用服务主体登录 Power BI 门户。You can't sign into the Power BI portal using service principal.
  • 在 Power BI 管理门户的开发人员设置中启用服务主体需要 Power BI 管理权限。Power BI admin rights are required to enable service principal in developer settings within the Power BI admin portal.
  • 无法使用服务主体安装或管理本地数据网关。You can't install or manage an on-premises data gateway using service principal.
  • 为组织嵌入内容应用程序无法使用服务主体。Embed for your organization applications are unable to use service principal.
  • 不支持数据流管理。Dataflows management is not supported.
  • 服务主体目前不支持任何管理员 API。Service principal currently does not support any admin APIs.

后续步骤Next steps