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. Using app owns data 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. 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 account is your master account) and a Microsoft Azure subscription.

Set up 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 Embedding setup 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 app 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 needs 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

Set up 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

    Publish desktop report

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

    PBI desktop report view in service

Embed your content using the sample application

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 Power BI master user account.
    • Fill in the pbiPassword with the password for the Power BI master user 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

Embed your content within your application

Even though the steps to embed your content can be done with the Power BI REST APIs, the example codes described in this article are made with the .NET SDK.

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 REST APIs.

To create the Power BI Client with your access token, you want to create your Power BI client object which allows you to interact with the Power BI REST APIs. This is done by wrapping the AccessToken with a Microsoft.Rest.TokenCredentials object.

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using Microsoft.Rest;
using Microsoft.PowerBI.Api.V2;

var tokenCredentials = new TokenCredentials(authenticationResult.AccessToken, "Bearer");

// Create a Power BI Client object. It is used to call Power BI APIs.
using (var client = new PowerBIClient(new Uri(ApiUrl), tokenCredentials))
{
    // Your code to embed items.
}

Get the content item you want to embed

You can use the Power BI client object to retrieve a reference to the item you want to embed.

Here is a code sample of how to retrieve the first report from a given workspace.

A sample of getting a content item whether it is a report, dashboard, or tile that you want to embed is available within the Controllers\HomeController.cs file in the sample application.

using Microsoft.PowerBI.Api.V2;
using Microsoft.PowerBI.Api.V2.Models;

// You need to provide the GroupID where the dashboard resides.
ODataResponseListReport reports = client.Reports.GetReportsInGroupAsync(GroupId);

// Get the first report in the group.
Report report = reports.Value.FirstOrDefault();

Create the embed token

An embed token needs to be generated which can be used from the JavaScript API. The embed token is specific to the item you are embedding. So at any time you embed a piece of Power BI content, you need to create a new embed token for it. For more information, including which accessLevel to use, see GenerateToken API.

Here is a sample of adding an embed token for a report to your application.

A sample of creating an embed token for a report, dashboard, or tile is available within the Controllers\HomeController.cs file in the sample application.

using Microsoft.PowerBI.Api.V2;
using Microsoft.PowerBI.Api.V2.Models;

// Generate Embed Token.
var generateTokenRequestParameters = new GenerateTokenRequest(accessLevel: "view");
EmbedToken tokenResponse = client.Reports.GenerateTokenInGroup(GroupId, report.Id, generateTokenRequestParameters);

// Generate Embed Configuration.
var embedConfig = new EmbedConfig()
{
    EmbedToken = tokenResponse,
    EmbedUrl = report.EmbedUrl,
    Id = report.Id
};

This assumes a class is created for EmbedConfig and TileEmbedConfig. A sample of these are available within the Models\EmbedConfig.cs file and the Models\TileEmbedConfig.cs file.

Load an item using JavaScript

You can use JavaScript to load a report into a div element on your web page.

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 can also get more Information about the JavaScript API by visiting the PowerBI-JavaScript wiki page.

Here is a sample that uses an EmbedConfig model and a TileEmbedConfig model along with views for a report.

A sample of adding a view for a report, dashboard, or tile is available within the Views\Home\EmbedReport.cshtml, Views\Home\EmbedDashboard.cshtml, or the Views\Home\Embedtile.cshtml files in the sample application.

<script src="~/scripts/powerbi.js"></script>
<div id="reportContainer"></div>
<script>
    // Read embed application token from Model
    var accessToken = "@Model.EmbedToken.Token";

    // Read embed URL from Model
    var embedUrl = "@Html.Raw(Model.EmbedUrl)";

    // Read report Id from Model
    var embedReportId = "@Model.Id";

    // Get models. models contains enums that can be used.
    var models = window['powerbi-client'].models;

    // Embed configuration used to describe the what and how to embed.
    // This object is used when calling powerbi.embed.
    // This also includes settings and options such as filters.
    // You can find more information at https://github.com/Microsoft/PowerBI-JavaScript/wiki/Embed-Configuration-Details.
    var config = {
        type: 'report',
        tokenType: models.TokenType.Embed,
        accessToken: accessToken,
        embedUrl: embedUrl,
        id: embedReportId,
        permissions: models.Permissions.All,
        settings: {
            filterPaneEnabled: true,
            navContentPaneEnabled: true
        }
    };

    // Get a reference to the embedded report HTML element
    var reportContainer = $('#reportContainer')[0];

    // Embed the report and display it within the div container.
    var report = powerbi.embed(reportContainer, config);
</script>

Move to production

Now that you've completed developing your application, it is time to back your app workspace with a 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. You can purchase a dedicated capacity within the Microsoft Azure portal. For details on how to create a Power BI Embedded capacity, see Create Power BI Embedded capacity in the Azure portal.

Use the table below to determine which Power BI Embedded capacity best fits your needs.

Capacity Node Total cores
(Backend + frontend)
Backend Cores Frontend Cores DirectQuery/live connection limits Max page renders at peak hour
A1 1 v-core(s) .5 core(s), 3GB RAM .5 cores 5 per second 1-300
A2 2 v-core(s) 1 core(s), 5GB RAM 1 cor(e) 10 per second 301-600
A3 4 v-core(s) 2 core(s), 10GB RAM 2 core(s) 15 per second 601-1,200
A4 8 v-core(s) 4 core(s), 25GB RAM 4 core(s) 30 per second 1,201-2,400
A5 16 v-core(s) 8 core(s), 50GB RAM 8 core(s) 60 per second 2,401-4,800
A6 32 v-core(s) 16 core(s), 100GB RAM 16 core(s) 120 per second 4,801-9600

With A SKUs, you cannot access Power BI content with a FREE Power BI license.

Using 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. The usage amount is based per master account.

For more details, see Embedded analytics capacity planning whitepaper.

Assign an app workspace to a dedicated capacity

Once you create a dedicated capacity, you can assign your app workspace to that 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

  3. After you select Save you should see a diamond next to the app workspace name.

    app workspace tied to a capacity

Next steps

In this tutorial, you've learned how to embed Power BI content into an application for your customers. You can also try to embed Power BI content for your organization.

More questions? Try asking the Power BI Community