Tutorial: Embed a Power BI report, dashboard or tile into an application for your customers
In this tutorial, you learn how to:
- Register an application in Azure.
- Embed a Power BI report into an application.
To get started, you need a Power BI Pro account (this is your master account) and a Microsoft Azure subscription.
- If you're not signed up for Power BI Pro, sign up for a free trial before you begin.
- If you don’t have an Azure subscription, create a free account before you begin.
- You need to have your own Azure Active Directory tenant setup.
- You need Visual Studio installed (version 2013 or later).
Setup your embedded analytics development environment
Before you start embedding reports, dashboard, or tiles into your application, you need to make sure your environment is set up to allow for embedding. As part of the setup, you need to do the following.
You can go through the Onboarding experience tool to quickly get started and download a sample application that helps you walk through creating an environment and embedding a report.
However, if you choose to set up the environment manually, you can continue below.
Register an application in Azure Active Directory (Azure AD)
You register your application with Azure Active Directory to allow your application access to the Power BI REST APIs. This allows you to establish an identity for your application and specify permissions to Power BI REST resources.
Accept the Microsoft Power BI API Terms.
Sign into the Azure portal.
In the left-hand navigation pane, choose All Services, select App Registrations and then select New application registration.
Follow the prompts and create a new application. For apps owns data you need to use Native for the application type. You also need to provide a Redirect URI, which Azure AD uses to return token responses. Enter a value specific to your application (for example: http://localhost:13526/redirect).
Apply permissions to your application within Azure Active Directory
You need to enable additional permissions for your application in addition to what was provided on the app registration page. You need to be logged in with the master account, used for embedding, which needs to be a global admin account.
Use the Azure Active Directory portal
Browse to App registrations within the Azure portal and select the app that you are using for embedding.
Select Settings, then under API Access select Required permissions.
Select Windows Azure Active Directory and then make sure Access the directory as the signed-in user is selected. Select Save.
Select Select an API.
Select Power BI Service, then select Select.
Select all permissions under Delegated Permissions. You need to select them one by one to save the selections. Select Save when done.
Within Required permissions, select Grant Permissions.
The Grant Permissions action is needed for the master account to avoid being prompted for consent by Azure AD. If the account performing this action is a Global Admin, you need to grant permissions to all users within your organization for this application. If the account performing this action is the master account and is not a Global Admin, you need to grant permissions only to the master account for this application.
Setup your Power BI environment
Create an app workspace
If you are embedding reports, dashboards, or tiles for your customers, then you have to place your content within an app workspace. The master account must be an admin of the app workspace.
Start by creating the workspace. Select workspaces > Create app workspace. This is where you place the content that your application needs to access.
Give the workspace a name. If the corresponding Workspace ID isn't available, edit it to come up with a unique ID. This needs to be the name of the app, too.
You have a few options to set. If you choose Public, anyone in your organization can see what’s in the workspace. Private, on the other hand, means only members of the workspace can see its contents.
You can't change the Public/Private setting after you've created the group.
You can also choose if members can edit or have view-only access.
Add email addresses of people you want to have access to the workspace, and select Add. You can’t add group aliases, just individuals.
Decide whether each person is a member or an admin. Admins can edit the workspace itself, including adding other members. Members can edit the content in the workspace unless they have view-only access. Both admins and members can publish the app.
Now you can view the new workspace. Power BI creates the workspace and opens it. It appears in the list of workspaces in which you’re a member. Because you’re an admin, you can select the ellipsis (…) to go back and make changes to it, adding new members or changing their permissions.
Create and publish your reports
You can create your reports and datasets using Power BI Desktop and then publish those reports to an app workspace. The end user publishing the reports need to have a Power BI Pro license to publish to an app workspace.
Download the sample Blog Demo from GitHub.
Open sample PBIX report in Power BI Desktop
Publish to the app workspace
Now you can view the report in the Power BI service online.
Embed your content
Embedding for your customers within your application requires you to get an access token for your master account from Azure AD. It is required to get an Azure AD access token for your Power BI application using app owns data before you make calls to the Power BI API.
Follow these steps to start embedding your content using a sample application.
Download the App Owns Data sample from GitHub to get started.
Open up the Web.config file in the sample application. There are 5 fields you need to fill in to run the application successfully. The clientId, the groupId, the reportId, the pbiUsername and the pbiPassword.
Fill in the clientId information with the Application ID from Azure. The clientId is used by the application to identify itself to the users from which you're requesting permissions. To get the clientId follow these steps:
Sign into the Azure portal.
In the left-hand navigation pane, choose All Services and select App Registrations.
Select the application that you want to get the clientId for.
You should see an Application ID that is listed as a GUID. Use this Application ID as the clientId for the application.
Fill in the groupId information with the app workspace GUID from Power BI.
Fill in the reportId information with the report GUID from Power BI.
- Fill in the pbiUsername with the master user Power BI account.
- Fill in the pbiPassword with the password for the master user Power BI account.
Run the application!
First select Run in Visual Studio.
Then select Embed Report. Depending on which content you choose to test with - reports, dashboards or tiles - then select that option in the application.
Now you can view the report in the sample application.
Move to production
Now that you're done developing your application, it is time to back your app workspace with dedicated capacity. Dedicated capacity is required to move to production.
Create a dedicated capacity
By creating a dedicated capacity, you can take advantage of having a dedicated resource for your customer. For workspaces that are not assigned to a dedicated capacity, these need to be in a shared capacity. You can create a dedicated capacity using the Power BI Embedded dedicated capacity solution in Azure.
Embed tokens with PRO licenses are intended for development testing, so the number of embed tokens a Power BI master account can generate is limited. You must purchase a dedicated capacity for embedding in a production environment. There is no limit on how many embed tokens you can generate with a dedicated capacity. Go to Available Features to check the usage value that indicates the current embedded usage in percentage.
Assign app workspace to dedicated capacity
Once dedicated capacity is created, assign the app workspace to the dedicated capacity. To complete this, follow these steps.
Within the Power BI service, expand workspaces and select the ellipsis for the workspace you're using for embedding your content. Then select Edit workspaces.
Expand Advanced, then enable Dedicated capacity, then select the dedicated capacity you created. Then select Save.
More questions? Try asking the Power BI Community