Learn about the steps you need to take to embed Power BI content within your application.

Microsoft recently announced Power BI Premium, a new capacity-based licensing model that increases flexibility for how users access, share and distribute content. The offering also delivers additional scalability and performance to the Power BI service.

With the introduction of Power BI Premium, Power BI Embedded and the Power BI service are converging to advance how Power BI content is embedded in apps. This means you will have one API surface, a consistent set of capabilities and access to the latest Power BI features – such as dashboards, gateways and app workspaces – when embedding your content. Moving forward you’ll be able to start with Power BI Desktop and move to deployment with Power BI Premium, which will be generally available late in the second quarter of 2017.

This article will look at embedding your Power BI content for both users of Power BI and non-Power BI users. The steps are similar between the two. Callouts will be made when a step is specific to embedding for non-Power BI users.

There are a few steps you have to do with your application to make this possible. We will go through the steps needed to allow you to create and use embedded content within your application.

Note:

The Power BI APIs still refer to app workspaces as groups. Any references to groups mean that you are working with app workspaces.

Step 1: Setup your embedded analytics development environment

Before you start embedding dashboards and reports into your application, you need to make sure your environment is setup to allow for embedding. As part of the setup, you will need to do the following.

Note:

Power BI Premium is not required for development of your application. The developers of the application will need to have a Power BI Pro license.

Azure Active Directory tenant

You will need an Azure Active Directory (Azure AD) tenant in order to embed items from Power BI. This tenant must have at least one Power BI Pro user. You will also need to define an Azure AD app within the tenant. You can make use of an existing Azure AD tenant or create a new one specifically for embedding purposes.

You will need to determine what tenant setup to use.

  • Use your existing corporate Power BI tenant?
  • Use a separate tenant for your application?
  • Use a separate tenant for each customer?

If you decide to create a new tenant for your application, or one for each customer, see Create an Azure Active Directory tenant or How to get an Azure Active Directory tenant.

Note:

It is recommended to create a new Azure AD tenant if you will be embedding for non-Power BI users.

Create a Power BI Pro user account

You only need a single Power BI Pro account to embed content. However, you may want to have a few different users that have specific access to items. Here is a look at possible users to consider within your tenant.

The following accounts will need to exist within your tenant and have a Power BI Pro license assigned to them.

Note:

These accounts will need to have Power BI Pro licenses in order to use App workspaces.

An organization/tenant admin user

It is recommended that your organization/tenant Global Admin user should not be used as the account your application uses. This is to minimize access that the application account has within your organization. It is recommended that the admin user be an admin of all App workspaces created for the purpose of embedding.

Accounts for analysts that will create content

You may have multiple users that create content for Power BI. You will need a Power BI Pro account for each analyst that is creating and deploying content to Power BI.

An application master user account for non-Power BI users

This is the account your application will use when embedding content for non-Power BI users. This is really the only required account you need within your organization. It can also be used as the admin and analyst account, but it is not recommended. Your application's backend will store the credentials for this account and use it for acquiring an Azure AD auth token for use with the Power BI APIs. This account will be used to generate an embed token for the application to use for non-Power BI users.

This account must be an admin of the app workspace that is being used for embedding.

App registration and permissions

You will need to register your application with Azure AD in order to make REST API calls. For more information, see Register an Azure AD app to embed Power BI content.

Create app workspaces

If you are embedding dashboards and reports for non-Power BI users (app owns data), those dashboards and reports have to be placed within an app workspace. For information on how to create an app workspace, see Create an app workspace.

Important:

The master account, that was mentioned above, needs to be an admin of the app workspace.

Create and upload 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 in order to publish to an app workspace.

Step 2: Embed your content

Within your application, you will need to authenticate with Power BI. If you are embedding content for non-Power BI users, this will require you to store the credentials for the master account within your application. For more information, see Authenticate users and get an Azure AD access token for your Power BI app.

After you have authenticated, within your application, use the Power BI and JavaScript APIs to embed dashboards and reports into your application.

For embedding with Power BI users (users own data), see the following:

For embeding with non-Power BI users (app owns data), which is typical for ISV scenarios, see the following:

When embedding for non-Power BI users (app owns data), an embed token is required. To learn more see, GenerateToken.

Step 3: Promote your solution to production

When you are ready to move to production, you will need to do the following.

Power BI users (user owns data)

If you are embedding for Power BI users, you only need to let people know how to get to your application.

Free users can consume content that is embedded from a group (app workspace), if that workspace is backed by a Premium capacity. The Free user needs to be listed as a member of group (app workspace), otherwise you will receive a 401 unauthorized error.

Non-Power BI users (app owns data)

If you are embedding for non-Power BI users, you will want to do the following.

  • While you can use your organizations production tenant, it is recommended to create a new embedded analytics environment for production. For more information, see Step 1 above.

  • If you are using a separate tenant for development, then you will need to make sure your app workspaces, along with dashboards and reports, are available in your production environment. You will also need to make sure that you created the application in Azure AD for your production tenant and assigned the proper app permissions as indicated in Step 1.

  • Purchase a capacity that fits your needs. You can use the table below to understand which Premium capacity SKU you may need. For more details, see Embedded analytics capacity planning whitepaper. When you are ready to purchase, you can do so within the Office 365 admin center.

Capacity Node Total cores
(Backend + frontend)
Backend Cores Frontend Cores DirectQuery/live connection limits Max page renders at peak hour Availability
EM1 1 v-cores .5 cores, 3GB RAM .5 cores 1-300 July 2017
EM2 2 v-cores 1 core, 5GB RAM 1 core 301-600 July 2017
EM3 4 v-cores 2 cores, 10GB RAM 2 cores 601-1,200 July 2017
P1 8 v-cores 4 cores, 25GB RAM 4 cores 30 per second 1,201-2,400 Available
P2 16 v-cores 8 cores, 50GB RAM 8 cores 60 per second 2,401-4,800 Available
P3 32 v-cores 16 cores, 100GB RAM 16 cores 120 per second 4,801-9600 Available
Note:

You must be a Global or Billing Admin, within your tenant, in order to purchase Power BI Premium. For information on how to purchase Power BI Premium, see How to purchase Power BI Premium.

  • Edit the App workspace and assign it to a Premium capacity under advanced.

  • Deploy your updated application to production and begin embedding reports from the Power BI service.

Admin settings

Global Admins, or Power BI service administrators, can turn the ability to use the REST APIs, on or off. Admins can set this setting for the entire organization, or for individual security groups. It is enabled for the entire organization by default. This is done through the Power BI admin portal.

Next steps

Embedding with Power BI
How to migrate Power BI Embedded workspace collection content to Power BI
Power BI Premium - what is it?
How to purchase Power BI Premium
JavaScript API Git repo
Power BI C# Git repo
JavaScript embed sample
Embedded analytics capacity planning whitepaper
Power BI Premium whitepaper

More questions? Try asking the Power BI Community