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
This article describes service principal authentication using Application ID and Application secret.
We recommend that you secure your backend services using certificates, rather than secret keys.
To use service principal and an application ID with embedded analytics, follow these steps:
Create an Azure AD app.
Create the Azure AD app's secret.
Get the app's Application ID and Application secret.
These steps are described in step 1. For more information about creating an Azure AD app, see the create an Azure AD app article.
Create an Azure AD security group.
Enable the Power BI service admin settings.
Add the service principal to your workspace.
Embed your content.
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
Log into Microsoft Azure.
Search for App registrations and click the App registrations link.
Click New registration.
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
After registering, the Application ID is available from the Overview tab. Copy and save the Application ID for later use.
Click the Certificates & secrets tab.
Click New client secret
In the Add a client secret window, enter a description, specify when you want the client secret to expire, and click Add.
Copy and save the Client secret value.
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.
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.
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.
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.
This section provides UI instructions. You can also add a service principal to a workspace using the Groups - add group user API.
Scroll to the workspace you want to enable access for, and from the More menu, select Workspace access.
Add the service principal as an Admin or Member to the workspace.
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.