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.
Azure AD recommends that you secure your backend services using certificates, rather than secret keys.
- Learn more about getting access tokens from Azure AD using secret keys or certificates.
- To secure your solution using a certificate, complete the instructions in this article and then follow the steps described in Embed Power BI content with service principal and a certificate.
To use service principal and an application ID 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:
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 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, or the security group that includes your service principal, as a member or admin to your workspace.
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.
Scroll to the workspace you want to enable access for, and from the More menu, select Workspace access.
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.
From the drop-down menu, select Member or Admin.
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.
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 only supports some read-only admin APIs. To enable service principal support for read-only admin APIs, you have to enable the Power BI service admin settings in your tenant. For more information, see Enable service principal authentication for read-only 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.