Tutorial: Embed a Power BI report, dashboard or tile into an application for your customers

With Power BI Embedded in Azure, you can embed reports, dashboards, or tiles into an application using app owns data. App owns data is about having an application that uses Power BI as its embedded analytics platform. This is typically an ISV developer scenario. As an ISV developer, you can create Power BI content that displays reports, dashboards, or tiles in an application that is fully integrated and interactive, without requiring users of the application to have a Power BI license or even be aware that it’s Power BI under the hood. This tutorial demonstrates how to integrate a report into an application using the Power BI .NET SDK along with the Power BI JavaScript API when using Power BI Embedded in Azure for your customers using app owns data.

In this tutorial, you learn how to:

  • Register an application in Azure.
  • Embed a Power BI report into an application.

Prerequisites

To get started, you need a Power BI Pro account (this is your master account) and a Microsoft Azure subscription.

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.

  1. Accept the Microsoft Power BI API Terms.

  2. Sign into the Azure portal.

    Azure Portal Main

  3. In the left-hand navigation pane, choose All Services, select App Registrations and then select New application registration.

    App registration search
    New App registration

  4. 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).

    Create App

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

  1. Browse to App registrations within the Azure portal and select the app that you are using for embedding.

    Choosing App

  2. Select Settings, then under API Access select Required permissions.

    Required Permissions

  3. Select Windows Azure Active Directory and then make sure Access the directory as the signed-in user is selected. Select Save.

    Windows Azure AD Permissions

  4. Select Add.

    Add Permissions

  5. Select Select an API.

    Add API Access

  6. Select Power BI Service, then select Select.

    Select PBI Services

  7. Select all permissions under Delegated Permissions. You need to select them one by one to save the selections. Select Save when done.

    Select delegated permissions

  8. 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.

    Grant permissions within required permissions dialog

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.

  1. Start by creating the workspace. Select workspaces > Create app workspace. This is where you place the content that your application needs to access.

    Create Workspace

  2. 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.

    Name Workspace

  3. 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.

    Private/Public

    You can't change the Public/Private setting after you've created the group.

  4. You can also choose if members can edit or have view-only access.

    Adding Members

  5. Add email addresses of people you want to have access to the workspace, and select Add. You can’t add group aliases, just individuals.

  6. 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.

    New workspace

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.

  1. Download the sample Blog Demo from GitHub.

    report sample

  2. Open sample PBIX report in Power BI Desktop

    PBI desktop report

  3. Publish to the app workspace

    PBI desktop report

    Now you can view the report in the Power BI service online.

    PBI desktop report

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.

  1. Download the App Owns Data sample from GitHub to get started.

    App Owns Data application sample

  2. 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.

    Web Config file

    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.

    Azure Portal Main

    In the left-hand navigation pane, choose All Services and select App Registrations.

    App registration search Select the application that you want to get the clientId for.

    Choosing App

    You should see an Application ID that is listed as a GUID. Use this Application ID as the clientId for the application.

    clientId

    Fill in the groupId information with the app workspace GUID from Power BI.

    groupId

    Fill in the reportId information with the report GUID from Power BI.

    reportId

    • 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.
  3. Run the application!

    First select Run in Visual Studio.

    Run the application

    Then select Embed Report. Depending on which content you choose to test with - reports, dashboards or tiles - then select that option in the application.

    Select a content

    Now you can view the report in the sample application.

    View 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.

Note

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.

  1. 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.

    Edit Workspace

  2. Expand Advanced, then enable Dedicated capacity, then select the dedicated capacity you created. Then select Save.

    Assign dedicated capacity

For a full sample of using the JavaScript API, you can use the Playground tool . This is a quick way to play with different types of Power BI Embedded samples. You also can get more Information about the JavaScript API by visiting the PowerBI-JavaScript wiki page.

For further questions about Power BI Embedded, please visit the FAQ page. If you are having issues with Power Bi Embedded within your application, then please visit the troubleshoot page.

More questions? Try asking the Power BI Community