Showing results for 
Search instead for 
Did you mean: 

Developing with Power BI Embedding (Part 1)

In the three years since its initial release, Power BI has become widely-adopted by corporations and other organizations as a Software-as-a-Service (SaaS) application. The Power BI Service provides licensed users with the ability to access and interact with Power BI reports and dashboards through the Power BI portal which most users access through the URL of The Power BI Service also provides licensed users with a first-class mobile experience using the Power BI Mobile apps that Microsoft has published for iPhone, Android and Windows 10. Microsoft promotes Power BI along with PowerApps and Flow as the primary services in the Microsoft Business Application Platform which offer customers a no code, low code approach to building custom business solutions.


In addition to its SaaS offerings, Power BI also provides developers with Platform-as-a-Service (PaaS) capabilities which make it possible to embed Power BI resources into custom applications. By learning to use a set of APIs created by the Power BI team at Microsoft, a developer can embed Power BI reports, dashboards and dashboard tiles into custom web applications that target the browsers, tablets and mobile devices.


This blog post focuses on the details and the developer skills required for developing with Power BI embedding and explains the essential concepts and terminology. As you will see, there are quite a few details you must learn when you get started. However, once you understand the landscape of Power BI embedding, you will be able to effectively extend the custom applications and components you are developing with interactive reports and dashboards.


Introduction to Power BI Embedding

Let's begin by examining how Power BI embedding works at a fundamental level. From an architectural perspective, Power BI embedding involves adding an iframe to a web page and configuring the iframe with a URL and a security token to load a Power BI report or dashboard directly from the Power BI Service. Figure 1 depicts a simple web page in a custom web application with an embedded Power BI report.



Figure 1: Power BI embedding is based on rendering a Power BI resource inside an iframe element.


The underlying architecture for Power BI embedding has been designed using open web standards including HTML5, CSS, JavaScript, OData, OAuth and OpenID Connect. This means that Power BI embedding techniques can be used by developers using a wide variety of programming languages and development platforms. These open standards also allow custom applications which use Power BI embedding to provide a wide reach to target any type of modern browser as well tablets and mobile devices.



Figure 2: The basic set of steps required to implement Power BI embedding.


The majority of applications that leverage Power BI embedding techniques are developed using a common pattern. The diagram in Figure 2 shows the typical sequence of steps involved when a custom application embeds a Power BI report on a web page. Let's walk through the steps.


  1. User launches the application.
  2. The application calls to Azure AD to obtain an access token to call the Power BI Service.
  3. The application calls the Power BI Service API to retrieve embedding data about a specific Power BI resource.
  4. The application passes the embedding data and a security token to client-side code running in the browser.
  5. Client-side code in the browser calls the Power BI JavaScript API to embed the Power BI resource.
  6. The Power BI JavaScript API dynamically creates the iframe and initializes the embedded resource.

There is an important observation here. Once a Power BI report has been embedded in the iframe, it has a direct connection back to the Power BI Service. This allows the users of your application to interact with the embedded report using familiar Power BI report features such as slicers and bookmarks.


Embeddable Resources

The PaaS features of the Power BI Service continue to evolve offering support for new types of embedded resources. Currently, the Power BI Service supports embedding for the following types of Power BI resources.


  • Power BI reports
  • Power BI dashboards
  • Power BI dashboard tiles
  • Power BI Q&A experience
  • Power BI report visuals

While you can embed several different types of Power BI resources, the list of supported features for each type is quite different. More specifically, embedded reports support quite a few extra features that are not supported by any of the other types. For example, you can embed a report in edit mode allowing the user to update the report layout and to save these changes back to the Power BI Service. It is also possible to embed a new report on top of an existing Power BI dataset allowing the user to create a report from scratch.


In a simple embed-it-and-forget-it scenario, you can just embed a report and rely on that report to supply its own interactive behavior using slicers, highlighting, drillthrough pages and bookmarks. But you can go far beyond that. Once you master the skills of developing with Power BI embedding, you'll be able to extend the interactive behavior of an embedded report by writing client-side code to set custom filters, apply bookmarks and set custom page layouts. Many developers today are using this approach to embed Power BI reports inside a user interface experience with a custom navigation scheme or a custom filtering experience.


Embedded dashboards do not provide the same level of interactive behavior when compared to embedded reports. For example, clicking on a tile inside an embedded dashboard does not redirect the user to a report page as it does when accessing the same dashboard through the Power BI portal. However, embedded dashboards do exhibit a modest amount of interactive behavior because hovering over a tile will still generate popup tooltips.


There is good news if you are working with real-time dashboards which you have built on top of streaming datasets, push datasets or hybrid datasets. You can embed a real-time dashboard in a custom application and it will continue to update itself automatically just as with dashboards that are accessed through the Power BI portal.


When you embed a dashboard, it is an all-or-nothing proposition when it comes to which tiles are displayed. But you also have the option to embed dashboard tiles individually. This can be handy when you want to select which tiles from a dashboard are displayed or you want more flexibility as to where each dashboard tile is displayed. One other thing to keep in mind that you cannot embed a tile from a real-time dashboard and see the updates in real time. When you are working with real-time dashboards, you must embed the entire dashboard and not individual dashboard tile.


The Q&A Experience is the newest arrival to the supported list of embeddable resources. If you have used the Q&A Experience in the Power BI portal, then you can imagine what the experience would look like when isolated by itself on your custom web page. When you embed the Q&A Experience, you must configure it by referencing an underlying dataset. You can also seed questions into the Q&A Experience to provide the user a starting point that will return results and display an initial visualization.


Now let's discuss how to embed a report visual. In truth, you cannot really embed a report visual by itself. Instead, you play a little trick. You embed the report which contains the visual and apply a custom layout to hide every other visual in the report except for the visual you want to display. You can implement a custom layout to reset the position, width and height of the visual so it occupies all the real estate inside the hosting iframe.


Custom report layouts can be applied dynamically after an embedded report has already loaded. This can lead to using custom layouts in creative ways. For example, let's say you embed a report with a custom layout that displays a single visual. You could then extend the user experience to provide some interactive control where the user can move from one visual to the next to iterate through all the visuals in the report. The user interface experience of switching between visuals will be very fast because the entire report has already been loaded into memory.


First-Party Embedding versus Third-Party Embedding

When initially designing a custom application which will implement Power BI embedding, you must decide between two development models: first-party embedding versus third-party embedding. Whichever of these two development models you choose will determine which user account will be used to authenticate with Azure AD to obtain the access token needed to call into the Power BI Service.


First-party embedding is known as the user-owns-data model. That's because you implement an Azure AD authentication flow to obtain an access token for the current user and you use the current user's identity and permissions to call into the Power BI Service API. First-party embedding is used in scenarios in which all users have an Azure AD user account and a Power BI user license. For example, a company using Office 365 and Power BI might decide to use first-party embedding to develop a custom Intranet-style application which surfaces Power BI reports and dashboards to an audience of users within a single Azure AD tenant.


While first-party embedding is a good fit for organizations using Power BI and Dynamics 365, it is not as useful for independent software vendors (ISVs) and other types of companies that provide SaaS applications to their customers. Third-party embedding is more attractive to ISVs because it can be used in scenarios in which users have neither Power BI licenses nor Azure AD user accounts. Therefore, an ISV can use third-party embedding in commercial applications that use a custom identity provider or some other identity provider service other than Azure AD.


ISVs like third-party embedding because there's no need to authenticate users with Azure AD or to acquire a Power BI license for each user. However, the lack of user licensing with third-party embedding begs an important question. If you are not paying Microsoft for Power BI through user licensing, how do you pay them for using the PaaS capabilities of the Power BI Service? The answer to that question involves dedicated capacities which are introduced in the next section.


There is a very important security aspect of Power BI embedding that differs between applications that use first-party embedding versus third-party embedded. While you must pass a security token to the browser to properly initialize the iframe with the embedded resource, the type of security token used between these two scenarios is different. When you use first-party embedding, you embed resources using an access token you retrieve from Azure AD when authenticating the current user.



Figure 3: First-party embedding involves embedding a resource using an Azure AD access token.


When using third-party embedding, you do not authenticate the current user with Azure AD, so you need to acquire a security token by some other means. This is accomplished by calling into the Power BI Service API to acquire a different type of security token known as an embed token.


There is a key observation here. An embed token is far more constrained than an Azure AD access token. That's because an embed token is specific to a single Power BI resource such as a report or a dashboard, When generating an embed token, you can specify the permissions you are granting such as view, edit and create. When using third-party embedding, you will generate a separate embed token for each Power BI resource that you need to embed on a web page.



Figure 4: Third-party embedding involves embedding a resource using an Power BI embed token.


Dedicated Capacities

It has never been a goal of Microsoft to become non-profit organization. Therefore, you should expect to pay licensing fees whenever using Power BI embedding features in a production environment. This is also true when using the PaaS features of the Power BI Service to implement Power BI embedding. For simple first-party embedding scenarios, acquiring a Power BI Pro license for each user might be all you need. For scenarios involving third-party embedding, you cannot pay Microsoft by purchasing user licenses because your users are unknown to Azure AD and the Power BI Service. Instead, you pay for third-party embedding by purchasing a license for a dedicated capacity.


A dedicated capacity is an isolated execution environment inside the Power BI cloud. When you purchase a license for a dedicated capacity, you are effectively paying Microsoft for the memory and the processing cycles that are used to serve up your Power BI content. In many (but not all) scenarios, a dedicated capacity runs on its own isolated hardware within a Microsoft data center. Running a dedicated capacity on its own isolated hardware improves performance and scalability because an organization does have to worry about sharing memory and processing cycles with other organizations in what is known as the "noisy neighbor" problem.


To take advantage of a dedicated capacity, you must create associations with Power BI workspaces. This includes both app workspaces and personal workspaces. Once a workspace has been associated with a dedicated capacity, all the content inside that workspace is then served up by the dedicated capacity.


Any workspace that has not been associated with a dedicated capacity runs within the context of a common execution environment known as the shared capacity. Since the shared capacity stores and serves content to many organizations at the same time, constraints are placed at the individual level and at the organizational level so that no one organization can monopolize shared capacity resources such as processing cycles and memory.


When you are working with an app workspace running in the shared capacity, there are some important limitations. For example, the datasets you create are limited to 1GB in size in memory. You are also limited in scheduling dataset refreshes to eight times a day. In order to move beyond these limitations, you must acquire a dedicated capacity.


When you need to acquire a dedicated capacity, you must choose between several different choices. First, you can acquire a dedicated capacity though Office 365 by purchasing Power BI Premium. Power BI Premium is available through two families of SKUs known as the P SKUs and EM SKUs. Alternatively, you can provision a dedicated capacity using the Power BI Embedded service in Microsoft Azure. When you create a dedicated capacity in Microsoft Azure using the Power BI Embedded service, you set its pricing tier using an A SKU. Therefore, acquiring a dedicated capacity requires you to choose between these three options.


  • Power BI Premium P SKU
  • Power BI Premium EM SKU
  • Power BI Embedded A SKU

Learning more about Power BI Embedding

I hope you enjoyed part 1 of this blog series on Power BI embedding. In part 2 of this blog series, I will examine the differences between Power BI Premium capacities and Power BI Embedded capacities and discuss how to set up an environment for developing with Power BI Embedding.


Are you really serious about learning Power BI embedding? If so, you should consider attending my new hands-on workshop titled Developing with Power BI Embedding. This workshop is two days in length and it will give you a wealth of hands-on experience with Power BI embedding as you work through a challenging track of real-world lab exercises. I will be running this workshop in Portland, OR on Novemeber 28 and 29.  I will be running this workshop a second time in sunny Tampa FL on December 18 and 19. You can find out more about the training classes I teach on the Critical Path Training website.



What is your favorite Power BI feature release for September 2023?