Tutorial: Embed Power BI content into an application for your customers

With Power BI Embedded in Azure or Power BI embedding in Office, 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. As an ISV or a 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 to have a Power BI license. This tutorial demonstrates how to integrate a report into an application using the Power BI .NET SDK with the Power BI JavaScript API.

Power BI Embed Report

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're required to have:

If you're not signed up for Power BI Pro, sign up for a free trial before you begin.

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 allows for embedding with Power BI.

You can go through the Embedding setup tool, so you can 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)

Register your application with Azure Active Directory to allow your application access to the Power BI REST APIs. Registering your application allows you to establish an identity for your application and specify permissions to Power BI REST resources. Depending if you want to use a master account or service principal, determines how to get started registering an application.

Depending on which method you take, affects which type of application you register in Azure.

If you proceed using a master account, then proceed with registering a Native app. You use a Native app because you're working with a non-interactive login.

However, if you proceed using the service principal, you need to proceed with registering a server-side web application app. You register a server-side web application to create an application secret.

Set up your Power BI environment

Create a workspace

If you're embedding reports, dashboards, or tiles for your customers, then you have to place your content within a workspace. There are different types of workspaces that you can set up: the traditional workspaces or the new workspaces. If you're using a master account, then it doesn't matter which type of workspaces you use. However, if you use service principal to sign into your application, then you're required to use the new workspaces. In either scenario, both the master account or service principal must be an admin of the workspaces involved with your application.

Create and publish your reports

You can create your reports and datasets using Power BI Desktop and then publish those reports to a workspace. There are two ways to accomplish this task: As an end user, you can publish reports to a traditional workspace with a master account (Power BI Pro license). If you're using service principal, you can publish reports to the new workspaces using the Power BI REST APIs.

The below steps walk through how to publish your PBIX report to your Power BI 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 workspaces. This process differs depending on whether you're using a master account (Power Pro license), or service principal. If you're using a master account, then you can publish your report through Power BI Desktop. Now if you're using service principal, you must use the Power BI REST APIs.

Embed content using the sample application

This sample is deliberately kept simple for demonstration purposes. It's up to the you or your developers to protect the application secret or the master account credentials.

Follow the steps below to start embedding your content using the sample application.

  1. Download Visual Studio (version 2013 or later). Make sure to download the latest NuGet package.

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

    App Owns Data application sample

  3. Open the Web.config file in the sample application. There are fields you need to fill in to run the application. You can choose MasterUser or ServicePrincipal for the AuthenticationType. Depending on which type of authentication method you choose there are different fields to complete.

    Note

    The default AuthenticationType in this sample is MasterUser.

    MasterUser
    (Power BI Pro license)
    ServicePrincipal
    (app-only token)
    applicationId applicationId
    workspaceId workspaceId
    reportId reportId
    pbiUsername
    pbiPassword
    applicationsecret
    tenant

    Web Config file

Application ID

This attribute is needed for both AuthenticationTypes (master account and service principal).

Fill in the applicationId information with the Application ID from Azure. The applicationId is used by the application to identify itself to the users from which you're requesting permissions.

To get the applicationId, follow these steps:

  1. Sign into the Azure portal.

  2. In the left-hand nav pane, select All Services, and select App Registrations.

    App registration search

  3. Select the application that needs the applicationId.

    Choosing App

  4. There's an Application ID that is listed as a GUID. Use this Application ID as the applicationId for the application.

    applicationId

Workspace ID

This attribute is needed for both AuthenticationTypes (master account and service principal).

Fill in the workspaceId information with the workspace (group) GUID from Power BI. You can get this information either from the URL when signed into the Power BI service or using Powershell.

URL

workspaceId

Powershell

Get-PowerBIworkspace -name "App Owns Embed Test"

workspaceId from powershell

Report ID

This attribute is needed for both AuthenticationTypes (master account and service principal).

Fill in the reportId information with the report GUID from Power BI. You can get this information either from the URL when signed into the Power BI service or using Powershell.

URL

reportId

Powershell

Get-PowerBIworkspace -name "App Owns Embed Test" | Get-PowerBIReport

reportId from powershell

Power BI username and password

These attributes are needed only for the master account AuthenticationType.

If you're using service principal to authenticate, then you don't need to fill in the username or password attributes.

  • Fill in the pbiUsername with the Power BI master account.
  • Fill in the pbiPassword with the password for the Power BI master account.

Application secret

This attribute is needed only for the service principal AuthenticationType.

Fill in the ApplicationSecret information from the Keys section of your App registrations section in Azure. This attribute works when using service principal.

To get the ApplicationSecret, follow these steps:

  1. Sign in to the Azure portal.

  2. In the left-hand nav pane, select All services and then select App registrations.

    App registration search

  3. Select the application that needs to use the ApplicationSecret.

    Choose an app

  4. Select Certificates and secrets under Manage.

  5. Select New client secrets.

  6. Enter a name in the Description box and select a duration. Then select Save to get the Value for your application. When you close the Keys pane after saving the key value, the value field shows only as hidden. At that point, you aren't able to retrieve the key value. If you lose the key value, create a new one in the Azure portal.

    Key value

Tenant

This attribute is needed only for the service principal AuthenticationType.

Fill in the tenant information with your azure tenant ID. You can get this information from the Azure AD admin center when signed into the Power BI service or by using Powershell.

Run the application

  1. Select Run in Visual Studio.

    Run the application

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

  3. Now you can view the report in the sample application.

    View application

Embed content within your application

Even though the steps to embed your content are 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 or service principal from Azure AD. You're required to get an Azure AD access token for your Power BI application 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. You create the Power BI client object 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's 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's a report, dashboard, or tile that you want to embed is available within the Services\EmbedService.cs file in the sample application.

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

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

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

Create the embed token

Generate an embed token, which can be used from the JavaScript API. There are two types of APIs, the first group contains five APIs, each generates an embed token for a specific item. The second group, which contains only one API, generates a token that can be used to embed multiple items.

APIs for generating an embed token for a specific item

The embed token created with these APIs is specific to the item you're embedding. Any time you embed a Power BI item (such as a report, dashboard, or tile) with these APIs, you need to create a new embed token for it.

Samples of creating an embed token for a report, dashboard, or tile, are available from the following files in the sample application.

  • Services\EmbedService.cs
  • Models\EmbedConfig.cs
  • Models\TileEmbedConfig.cs

Below is a code example for using the reports GenerateTokenInGroup embed token API.

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(workspaceId, report.Id, generateTokenRequestParameters);

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

API for generating an embed token for multiple items

The Generate Token embed API generates a token that can be used for embedding multiple items.

It can also be used for dynamically selecting a dataset while embedding a report. For more information about this use of the API, see dynamic binding.

Below is an example of using this API.

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

var reports = new List<GenerateTokenRequestV2Report>()
{ 
    new GenerateTokenRequestV2Report()
    {
        AllowEdit = false,
        Id = report1.Id
    },
    new GenerateTokenRequestV2Report()
    {
        AllowEdit = true,
        Id = report2.Id
    }
};

var datasets= new List<GenerateTokenRequestV2Dataset>()
{
    new GenerateTokenRequestV2Dataset(dataset1.Id),
    new GenerateTokenRequestV2Dataset(dataset2.Id),
    new GenerateTokenRequestV2Dataset(dataset3.Id),
};

var targetWorkspaces = new List<GenerateTokenRequestV2TargetWorkspace>()
{
    new GenerateTokenRequestV2TargetWorkspace(workspace1.Id),
    new GenerateTokenRequestV2TargetWorkspace(workspace2.Id),
};

var request = new GenerateTokenRequestV2()
{
    Datasets = datasetsRequestDetails ?? null,
    Reports = reportsRequestDetails,
    TargetWorkspaces = targetWSRequestdetials ?? null,
};

var token = client.GetClient().EmbedToken.GenerateToken(request);

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. The Playground tool 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 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 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's time to back your workspace with a dedicated capacity.

Important

Dedicated capacity is required to move to production. All workspaces (the ones containing the reports or dashboards, and the ones containing the datasets) must be assigned to a capacity.

Create a dedicated capacity

By creating a dedicated capacity, you can take advantage of having a dedicated resource for your customer. There are two types of capacity you can choose from:

  • Power BI Premium - A tenant-level Office 356 subscription available in two SKU families, EM and P. When embedding Power BI content, this solution is referred to as Power BI embedding. For more informtion regarding this subscription, see What is Power BI Premium?
  • Azure Power BI Embedded - You can purchase a dedicated capacity from the Microsoft Azure portal. This subscription uses the A SKUs. For details on how to create a Power BI Embedded capacity, see Create Power BI Embedded capacity in the Azure portal.

Note

With A SKUs, you can't access Power BI content with a FREE Power BI license.

The table below describes the resources and limits of each SKU. To determine which capacity best fits your needs, see the which SKU should I purchase for my scenario table.

Capacity Nodes Total v-cores Backend v-cores RAM (GB) Frontend v-cores DirectQuery/Live Connection (per sec) Model Refresh Parallelism
EM1/A1 1 0.5 2.5 0.5 3.75 1
EM2/A2 2 1 5 1 7.5 2
EM3/A3 4 2 10 2 15 3
P1/A4 8 4 25 4 30 6
P2/A5 16 8 50 8 60 12
P3/A6 32 16 100 16 120 24

Development testing

Using embed tokens with Pro licenses are intended for development testing, so the number of embed tokens a Power BI master account or service principal can generate is limited. A dedicated capacity requires embedding in a production environment. There's 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 information, see Embedded analytics capacity planning whitepaper.

Assign a workspace to a dedicated capacity

Once you create a dedicated capacity, you can assign your workspace to that dedicated capacity.

To assign a dedicated capacity to a workspace using service principal, use the Power BI REST API. When you are using the Power BI REST APIs, make sure to use the service principal object ID.

Follow the steps below to assign a dedicated capacity to a workspace using a master account.

  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 workspace name.

    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