Tutorial: Embed Power BI content using a sample embed for your customers' application

APPLIES TO:  App owns data  User owns data

Embedded analytics and Power BI Embedded (the Azure offer) allow you to embed Power BI content such as reports, dashboards and tiles, into your application.

In this tutorial, you'll learn how to:

• Set up your embedded environment.
• Configure an embed for your customers (also known as app owns data) sample application.

To use your application, your users won't need to sign in to Power BI or have a Power BI license.

We recommend using the embed for your customers method to embed your Power BI content, if you're an independent software vendor (ISV) or a developer, who wants to create applications for third parties.

Important

If you are embedding content for a national/regional cloud, the first few steps of this tutorial are different. See Embed content for national/regional clouds for details.

Code sample specifications

This tutorial includes instructions for configuring an embed for your customers sample application in one of the following frameworks:

• .NET Framework
• .NET Core
• Java
• Node JS
• Python

The code samples support the following browsers:

• Microsoft Edge
• Google Chrome
• Mozilla Firefox

Prerequisites

Before you start this tutorial, verify that you have both the Power BI and code dependencies listed below:

• Power BI dependencies

  • Your own Azure Active Directory tenant.

  • To authenticate your app against Power BI, you'll need one of the following:

    • Service principal - An Azure Active Directory (Azure AD) service principal object that allows Azure AD to authenticate your app.

    • Power BI Pro license - This will be your master user and your app will use it to authenticate to Power BI.

    • A Power BI Premium Per User (PPU) license - This will be your master user and your app will use it to authenticate to Power BI.

    Note

    To move to production you'll need a capacity.

• Code dependencies

.NET Core

• .NET Core 3.1 SDK (or higher)

• An integrated development environment (IDE). We recommend using one of the following:

  • Visual Studio

  • Visual Studio Code

.NET Framework

• .NET Framework 4.8

• Visual Studio

Java

• JDK (or JRE)

• Eclipse IDE - Verify that you have the Eclipse for Java EE Developers (enterprise edition)

• Apache Tomcat Binary Distributions

Node JS

• Node.js

• An integrated development environment (IDE). We recommend using one of the following:

  • Visual Studio

  • Visual Studio Code

Python

• Python 3 (or higher)

  Note

  • If you're installing Python for the first time, select the Add Python to PATH option, to add the installation to the PATH variable.
  • If you already have Python installed, verify that the PATH variable includes its installation path. For more information, see the Excursus: Setting environment variables Python documentation (this link refers to Python 3).

• An integrated development environment (IDE). We recommend using one of the following:

  • Visual Studio

  • Visual Studio Code

Method

To create an embed for your customers sample app, follow these steps:

1. Select your authentication method.

2. Register an Azure AD application.

3. Create a Power BI workspace.

4. Create and publish a Power BI report.

5. Get the embedding parameter values.

6. Service principal API access

7. Enable workspace access.

8. Embed your content.

Step 1 - Select your authentication method

Your embedded solution will vary depending on the authentication method you select. Therefore, it's important to understand the differences between the authentication methods, and decide which one best suits your solution.

The table below describes a few key differences between the service principal and master user authentication methods.

Consideration	Service principal	Master user
Mechanism	Your Azure AD app's service principal object allows Azure AD to authenticate your embedded solution app against Power BI.	Your Azure AD app uses the credentials (username and password) of a Power BI user, to authenticate against Power BI.
Security	Service principal is the Azure AD recommended authorization method. If you're using a service principal, you can authenticate using either an application secret or a certificate. This tutorial only describes using service principal with an application secret. To embed using a service principal and a certificate, refer to the service principal with a certificate article.	This authentication method isn't as secure as a service principal. You have to be vigilant with the master user credentials (username and password). For example, don't expose them in your embedding application, and change the password frequently.
Azure AD delegated permissions	Not required.	Your master user or an administrator has to grant consent for your app to access Power BI REST API permissions (also known as scopes). For example, Report.ReadWrite.All.
Power BI service access	You can't access Power BI service with a service principal.	You can access Power BI service with your master user credentials.
License	Doesn't require a Pro license. You can use content from any workspace that you're a member or an admin of.	Requires a Power BI Pro or Premium Per User (PPU) license.

Step 2 - Register an Azure AD application

Registering your application with Azure AD allows you to:

• Establish an identity for your app
• Let your app access the Power BI REST APIs
• If you're using a master user - Specify your app's Power BI REST permissions

To register your application with Azure AD, follow the instructions in Register your application.

Note

Before registering your application, you'll need to decide which authentication method to use, service principal or master user.

Step 3 - Create a Power BI workspace

Power BI keeps your reports, dashboards, and tiles in a workspace. To embed these items, you'll need to create them and upload them into a workspace.

Tip

If you already have a workspace, you can skip this step.

To create a workspace, do the following:

1. Sign in to Power BI.

2. Select Workspaces.

3. Select Create a workspace.

4. Name your workspace and select Save.

Step 4 - Create and publish a Power BI report

Your next step is to create a report and upload it to your workspace. You can create your own report using Power BI Desktop, and then publish it to your workspace. Or, you can upload a sample report to your workspace.

Tip

If you already have a workspace with a report, you can skip this step.

To download a sample report and publish it to your workspace, follow these steps:

1. Open the GitHub Power BI Desktop samples folder.

2. Select Code and then select Download zip.

   

3. Extract the downloaded ZIP and navigate to the Samples Reports folder.

4. Select a report to embed, and publish it to your workspace.

Step 5 - Get the embedding parameter values

To embed your content, you need to obtain certain parameter values. The table below shows the required values, and indicates if they're applicable to the service principal authentication method, the master user authentication method, or both.

Before you embed your content, make sure you have all the values listed below. Some of the values will differ, depending on the authentication method you're using.

Parameter	Service principal	Master user
Client ID
Workspace ID
Report ID
Client secret
Tenant ID		required only for Node JS
Power BI username
Power BI password

Client ID

Tip

Applies to: Service principal Master user

To get the client ID GUID (also know as application ID), follow these steps:

1. Log into Microsoft Azure.

2. Search for App registrations and select the App registrations link.

3. Select the Azure AD app you're using for embedding your Power BI content.

4. From the Overview section, copy the Application (client) ID GUID.

Workspace ID

Tip

Applies to: Service principal Master user

To get the workspace ID GUID, follow these steps:

1. Sign in to Power BI service.

2. Open the report you want to embed.

3. Copy the GUID from the URL. The GUID is the number between /groups/ and /reports/.

   

Alternatively, you can find the workspace ID in the Admin portal settings by selecting Details next to the workspace name.

Report ID

Tip

Applies to: Service principal Master user

To get the report ID GUID, follow these steps:

1. Sign in to Power BI service.

2. Open the report you want to embed.

3. Copy the GUID from the URL. The GUID is the number between /reports/ and /ReportSection.

   

Client secret

Tip

Applies to: Service principal Master user

To get the client secret, follow these steps:

1. Log into Microsoft Azure.

2. Search for App registrations and select the App registrations link.

3. Select the Azure AD app you're using for embedding your Power BI content.

4. Under Manage, select Certificates & secrets.

5. Under Client secrets, select New client secret.

6. In the Add a client secret pop-up window, provide a description for your application secret, select when the application secret expires, and select Add.

7. From the Client secrets section, copy the string in the Value column of the newly created application secret. The client secret value is your client ID.

Note

Make sure you copy the client secret value when it first appears. After navigating away from this page, the client secret will be hidden and you'll not be able to retrieve its value.

Tenant ID

Tip

Applies to: Service principal Master user

To get the tenant ID GUID, follow these steps:

1. Log into Microsoft Azure.

2. Search for App registrations and select the App registrations link.

3. Select the Azure AD app you're using for embedding your Power BI content.

4. From the Overview section, copy the Directory (tenant) ID GUID.

Power BI username and password

Tip

Applies to: Service principal Master user

Obtain the username and password of the Power BI user you're using as your master user. This is the same user you used to create a workspace and upload a report to, in Power BI service.

Step 6 - Service principal API access

Tip

Applies to: Service principal Master user

This step is only relevant if you're using the service principal authentication method. If you're using a master user, skip this step and continue with Step 7 - Enable workspace access.

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. If you're not the admin of your tenant, get the tenant's admin to enable the Tenant settings for you.

1. In Power BI service, select Settings > Settings > Admin portal.

   

2. Select Tenant settings and then scroll down to the Developer settings section.

3. Expand Allow service principals to use Power BI APIs, and enable this option.

   

Note

When using a service principal, it's recommended to limit its access to the tenant settings using a security group. To learn more about this feature, see these sections in the service principal article:

• Create an Azure AD security group
• Enable the Power BI service admin settings

Step 7 - Enable workspace access

To enable your Azure AD app access objects such as reports, dashboards and datasets in the Power BI service, add the service principal or master user, as a member or admin to your workspace.

1. Sign in to Power BI service.

2. Scroll to the workspace you want to enable access for, and from the More menu, select Workspace access.

   

3. In the Access pane, depending on which authentication method you're using, copy the service principal or master user to the Enter email address text box.

   Note

   If you're using a service principal, its name is the name you gave your Azure AD app.

4. Select Add.

Step 8 - Embed your content

The Power BI embedded sample application allows you to create an embed for your customers Power BI app.

Follow these steps to modify the embed for your customers sample application, to embed your Power BI report.

1. Open the Power BI developer samples folder.

2. Select Code and then select Download zip.

   

3. Extract the downloaded ZIP and navigate to the PowerBI-Developer-Samples-master folder.

4. Depending on the language you want your app to use, open one of these folders:

   • .NET Core
   • .NET Framework
   • Java
   • Node JS
   • Python

   Note

   The embed for your customers sample applications only support the frameworks listed above. The React sample application only supports the embed for your organization solution.

5. Open the Embed for your customers folder.

.NET Core

6. Open the embed for your customers sample app using one of these methods:

   • If you're using Visual Studio, open the AppOwnsData.sln file.

   • If you're using Visual Studio Code, open the AppOwnsData folder.

7. Open appsettings.json.

8. Depending on your authentication method, fill in the following parameter values:

   Parameter	Service principal	Master user
   AuthenticationMode	ServicePrincipal	MasterUser
   ClientId	Your Azure AD app client ID	Your Azure AD app client ID
   TenantId	Your Azure AD tenant ID	N/A
   PbiUsername	N/A	Your master user username, see Power BI username and password
   PbiPassword	N/A	Your master user password, see Power BI username and password
   ClientSecret	Your Azure AD client secret	N/A
   WorkspaceId	The ID of the workspace with your embedded report, see Workspace ID	The ID of the workspace with your embedded report, see Workspace ID
   ReportId	The ID of the report you're embedding, see Report ID	The ID of the report you're embedding, see Report ID

9. Run the project by selecting the appropriate option:

   • If you're using Visual Studio, select IIS Express (play).

   • If you're using Visual Studio Code, select Run > Start Debugging.

.NET Framework

6. Using Visual Studio, open the AppOwnsData.sln file.

7. Open Web.config.

8. Depending on your authentication method, fill in the following parameter values:

   Parameter	Service principal	Master user
   authenticationType	ServicePrincipal	MasterUser
   applicationId	Your Azure AD app client ID	Your Azure AD app client ID
   workspaceId	The ID of the workspace with your embedded report, see Workspace ID	The ID of the workspace with your embedded report, see Workspace ID
   reportId	The ID of the report you're embedding, see Report ID	The ID of the report you're embedding, see Report ID
   pbiUsername	N/A	Your master user username, see Power BI username and password
   pbiPassword	N/A	Your master user password, see Power BI username and password
   applicationSecret	Your Azure AD client secret	N/A
   tenant	Your Azure AD tenant ID	N/A

9. Run the project by selecting IIS Express (play).

Java

6. Open Eclipse and follow the instructions described below.

   Note

   The instructions for the Java embed for your customers sample app, refer to Eclipse IDE for Java EE Developers (enterprise edition). If you're using a different application, you'll have to set it up yourself.

7. Add the Tomcat server to Eclipse:

   a. Select Window > Show View > Servers.

   b. In the servers tab, select No servers are available. Click this link to create new server.

   c. In the Define a New Server window, expand Apache and select the Tomcat server you're running on your machine. For example, Tomcat v9.0 Server.

   d. Select Next.

   e. In the Tomcat Server window, select Browse and navigate to the folder that contains the Tomcat server.

   f. In the Tomcat Server window, select Installed JREs.

   g. In the Installed JREs window, select the available jre, and select Apply and Close.

   h. In the Tomcat Server window, select Finish. You'll be able to see the Tomcat server in the Servers tab.

8. Open the project in Eclipse:

   Important

   Eclipse may run into trouble if your path name is too long. To avoid this issue, verify that your sample app's folder is not nested too deeply in your machine's folder structure.

   a. Select File and then select Open Projects from File System.

   b. In the Import Projects from File System or Archive window, select Directory and open the AppOwnsData folder.

   c. Select Finish.

9. Add the Tomcat server to the project:

   a. In the Package Explorer pane, right-click AppOwnsData, and select Properties.

   b. In the Properties for AppOwnsData window, select Targeted Runtimes and then select Apache Tomcat. This selection will include the version of Apache Tomcat you're using, for example Apache Tomcat v9.0.

   c. Select Apply and Close.

10. Fill in the required parameters

    a. In the Package explorer, expand the AppOwnsData project.

    b. Expand Java Resources.

    c. Expand src.

    d. Expand com.embedsample.appoensdata.config.

    e. Open Config.java.

    f. Depending on your authentication method, fill in the following parameter values:

    Parameter	Service principal	Master user
    authenticationType	ServicePrincipal	MasterUser
    workspaceId	The ID of the workspace with your embedded report, see Workspace ID	The ID of the workspace with your embedded report, see Workspace ID
    reportId	The ID of the report you're embedding, see Report ID	The ID of the report you're embedding, see Report ID
    clientId	Your Azure AD app client ID	Your Azure AD app client ID
    pbiUsername	N/A	Your master user username, see Power BI username and password
    pbiPassword	N/A	Your master user password, see Power BI username and password
    tenantId	Your Azure AD tenant ID	N/A
    appSecret	Your Azure AD client secret	N/A

11. Run the project

    a. In the Package Explorer, right-click AppOwnesData.

    b. Select Run As > Run on Server.

    c. In the Run on Server window, select Choose an existing server and select the Tomcat server.

    d. Select Finish.

Node JS

6. Open the App Owns Data folder using your preferred IDE. We recommend using one of the following:

   • Visual Studio

   • Visual Studio Code

7. Open a terminal and install the required dependencies by executing: npm install.

8. Expand the Config folder and open config.json.

9. Depending on your authentication method, fill in the following parameter values:

   Parameter	Service principal	Master user
   authenticationMode	ServicePrincipal	MasterUser
   clientId	Your Azure AD app client ID	Your Azure AD app client ID
   workspaceId	The ID of the workspace with your embedded report, see Workspace ID	The ID of the workspace with your embedded report, see Workspace ID
   reportId	The ID of the report you're embedding, see Report ID	The ID of the report you're embedding, see Report ID
   pbiUsername	N/A	Your master user username, see Power BI username and password
   pbiPassword	N/A	Your master user password, see Power BI username and password
   clientSecret	Your Azure AD client secret	N/A
   tenantId	Your Azure AD tenant ID	Your Azure AD tenant ID

10. Run the project by doing the following:

    a. In the IDE terminal, execute npm start.

    b. Open a new tab in your browser and navigate to http://localhost:5300.

Python

6. Open PowerShell or Command Prompt.

7. Verify that you're in the Python > Embed for your customers folder, and that the file requirements.txt is in the folder, and run pip3 install -r requirements.txt.

8. Open the App Owns Data folder using your preferred IDE. We recommend using one of the following:

   • Visual Studio

   • Visual Studio Code

9. Open config.py.

10. Depending on your authentication method, fill in the following parameter values:

    Parameter	Service principal	Master user
    AUTHENTICATION_MODE	ServicePrincipal	MasterUser
    WORKSPACE_ID	The ID of the workspace with your embedded report, see Workspace ID	The ID of the workspace with your embedded report, see Workspace ID
    REPORT_ID	The ID of the report you're embedding, see Report ID	The ID of the report you're embedding, see Report ID
    TENANT_ID	Your Azure AD tenant ID	N/A
    CLIENT_ID	Your Azure AD app client ID	Your Azure AD app client ID
    CLIENT_SECRET	Your Azure AD client secret	N/A
    POWER_BI_USER	N/A	Your master user username, see Power BI username and password
    POWER_BI_PASS	N/A	Your master user password, see Power BI username and password

11. Save the file.

12. Run the project by doing the following:

    a. In PowerShell or Command Prompt, navigate to the Python > Embed for your customers > AppOwnesData folder, and execute flask run.

    b. Open a new tab in your browser and navigate to http://localhost:5000.

Developing your application

After configuring and running the embed for your customers sample application, you can start developing your own application.

Try out the Power BI embedded analytics playground to get started developing and to keep up with all the new Power BI Embedded features and updates.

When you're ready, review the move to production requirements. You'll also need a capacity, and should review the capacity planning article to establish which SKU best suits your needs.

Important

If you used free embed trial tokens for development, you must buy a capacity for production. Until a capacity is purchased, the Free trial version banner will continue to appear at the top of the embedded report.

Next steps

• Move to production
• Embed for your organization
• Embed paginated reports

More questions? Ask the Power BI Community.