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:

  • Application secret
  • Certificate

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

Note

We recommend that you secure your backend services using certificates, rather than secret keys.

Method

To use service principal and an application ID with 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.

    application ID

  1. Click the Certificates & secrets tab.

    application ID

  2. Click New client secret

    new client secret

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

  4. Copy and save the Client secret value.

    client secret value

    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:

  • Manually (in Azure)
  • Using PowerShell

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 a tenant 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.

Admin portal

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 as a member or admin to your workspace.

Note

This section provides UI instructions. You can also add a service principal 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.

    Workspace settings

  2. Add the service principal as an Admin or Member to the workspace.

    Workspace admin

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.

Considerations and limitations

  • Service principal only works with new workspaces.
  • My Workspace isn't supported when using service principal.
  • Dedicated 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