Embed Power BI content with service principal and an application secret

Service principal is an authentication method that can be used to let an Azure AD application access Power BI service content and APIs.

When you create an Azure Active Directory (Azure AD) app, a service principal object is created. The service principal object, also known simply as service principal, allows Azure AD to authenticate your app. Once authenticated, the app can access Azure AD tenant resources.

To authenticate, the service principal uses the Azure AD app's Application ID, and one of the following:

  • Certificate
  • Application secret

This article describes service principal authentication using Application ID and Application secret.

Note

Azure AD recommends that you secure your backend services using certificates, rather than secret keys.

Method

To use service principal and an application ID embedded analytics, follow these steps:

  1. Create an Azure AD app.

    1. Create the Azure AD app's secret.

    2. Get the app's Application ID and Application secret.

    Note

    These steps are described in step 1. For more information about creating an Azure AD app, see the create an Azure AD app article.

  2. Create an Azure AD security group.

  3. Enable the Power BI service admin settings.

  4. Add the service principal to your workspace.

  5. Embed your content.

Important

Once you enable service principal to be used with Power BI, the application's AD permissions don't take effect anymore. The application's permissions are then managed through the Power BI admin portal.

Step 1 - Create an Azure AD app

Create an Azure AD app using one of these methods:

Creating an Azure AD app in the Microsoft Azure portal

  1. Log into Microsoft Azure.

  2. Search for App registrations and click the App registrations link.

    azure app registration

  3. Click New registration.

    new registration

  4. Fill in the required information:

    • Name - Enter a name for your application
    • Supported account types - Select supported account types
    • (Optional) Redirect URI - Enter a URI if needed
  5. Click Register.

  6. After registering, the Application ID is available from the Overview tab. Copy and save the Application ID for later use.

    Screenshot shows where to obtain an Application I D in the Overview tab.

  7. Click the Certificates & secrets tab.

    A screenshot that shows the certificates and secrets pane for an app in the Azure portal.

  8. Click New client secret

    A screenshot that shows the new client secret button in the certificates and secrets pane.

  9. In the Add a client secret window, enter a description, specify when you want the client secret to expire, and click Add.

  10. Copy and save the Client secret value.

    A screenshots that shows a blurred out secret value in the certificates and secrets pane.

    Note

    After you leave this window, the client secret value will be hidden, and you'll not be able to view or copy it again.

Creating an Azure AD app using PowerShell

This section includes a sample script to create a new Azure AD app using PowerShell.

# The app ID - $app.appid
# The service principal object ID - $sp.objectId
# The app key - $key.value

# Sign in as a user that's allowed to create an app
Connect-AzureAD

# Create a new Azure AD 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

Step 2 - Create an Azure AD security group

Your service principal doesn't have access to any of your Power BI content and APIs. To give the service principal access, create a security group in Azure AD, and add the service principal you created to that security group.

There are two ways to create an Azure AD security group:

Create a security group manually

To create an Azure security group manually, follow the instructions in the Create a basic group and add members using Azure Active Directory article.

Create a security group using PowerShell

Below is a sample script for creating a new security group, and adding an app to that security group.

Note

If you want to enable service principal access for the entire organization, skip this step.

# Required to sign in as admin
Connect-AzureAD

# Create an Azure AD 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)

Step 3 - Enable the Power BI service admin settings

For an Azure AD app to be able to access the Power BI content and APIs, a Power BI admin needs to enable service principal access in the Power BI admin portal.

Add the security group you created in Azure AD, to the specific security group section in the Developer settings.

Important

Service principals have access to any tenant settings they're enabled for. Depending on your admin settings, this includes specific security groups or the entire organization.

To restrict service principal access to specific tenant settings, allow access only to specific security groups. Alternatively, you can create a dedicated security group for service principals, and exclude it from the desired tenant settings.

Screenshot showing the developer settings in the admin options in Power B I service.

Step 4 - Add the service principal to your workspace

To enable your Azure AD app access artifacts such as reports, dashboards and datasets in the Power BI service, add the service principal entity, or the security group that includes your service principal, as a member or admin to your workspace.

Note

This section provides UI instructions. You can also add a service principal or a security group to a workspace, using the Groups - add group user API.

  1. Scroll to the workspace you want to enable access for, and from the More menu, select Workspace access.

    Screenshot showing the workspace access button in the more menu of a Power BI workspace.

  2. In the Access pane, text box, add one of the following:

    • Your service principal. The name of your service principal is the Display name of your Azure AD app, as it appears in your Azure AD app's overview tab.

    • The security group that includes your service principal.

  3. From the drop-down menu, select Member or Admin.

  4. Select Add.

Add a service principal as a workspace member using PowerShell

This section includes a sample script to add a service principal as a workspace member using PowerShell.

Login-PowerBI

# Service Principal Object ID for the created Service Principal
$SPObjectId = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

$pbiWorkspace = Get-PowerBIWorkspace -Name "YourWorkspaceName"

Add-PowerBIWorkspaceUser -Id $pbiWorkspace.Id -AccessRight Member -PrincipalType App -Identifier $SPObjectId 

Add a security group as a workspace member using PowerShell

This section includes a sample script to add a security group as a workspace member using PowerShell.

Login-PowerBI

# Security Group Object ID for the created Security Group
$SGObjectId = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

$pbiWorkspace = Get-PowerBIWorkspace -Name "YourWorkspaceName"

Add-PowerBIWorkspaceUser -Id $pbiWorkspace.Id -AccessRight Member -PrincipalType Group -Identifier $SGObjectId 

Step 5 - Embed your content

You can embed your content within a sample application, or within your own application.

Once your content is embedded, you're ready to move to production.

Note

To secure your content using a certificate, follow the steps described in Embed Power BI content with service principal and a certificate.

Considerations and limitations

  • Service principal only works with new workspaces.
  • My Workspace isn't supported when using service principal.
  • A capacity is required when moving to production.
  • You can't sign into the Power BI portal using service principal.
  • Power BI admin rights are required to enable service principal in developer settings within the Power BI admin portal.
  • Embed for your organization applications can't use service principal.
  • Dataflows management is not supported.
  • Service principal currently does not support any admin APIs.
  • When using service principal with an Azure Analysis Services data source, the service principal itself must have an Azure Analysis Services instance permissions. Using a security group that contains the service principal for this purpose, doesn't work.

Next steps