Power BI already has an easy way to embed Power BI reports into public websites with Publish to web and to secure SharePoint Online pages with the Power BI web part. However, embedding content into internal sites required advanced coding skills. Now, with the new secure Embed option, you can easily integrate your report with any internal site or portal so long as it allows embedding using an HTML code snippet or a URL.
This new option enables business users who do not have any coding skills to easily and securely embed reports in internal web portals, whether cloud-based or hosted on-premises. Reports embedded in this way respect all item permissions set in Power BI and data security through row-level security (RLS).
The Embed option also supports basic URL Filters and URL settings, which allow you to build experiences into your portals using rudimentary HTML and JavaScript skills. We’ll see an example later in this blog.
Getting started with the new secure Embed option
The new Embed option is available on the File menu for reports in the Power BI service.
Select the Embed option to open a dialog that provides a link and an HTML snippet that can be used to embed the report securely. You’ll need to use use your portal’s embed feature or edit the web page’s HTML to add the report.
After the report is embedded in your web portal, or if a user opens the URL directly, the user is authenticated before they can access to the report. Below, the user has not signed-in to Power BI in the browser session. When they press Sign-In, a new browser window or tab may need to open, so ensure you check for pop-up blockers if you do not get prompted to sign-in. The user needs to sign-in each time they open a new browser window. After they’ve signed in once other reports will load automatically.
After the user has signed-in, the report will open, showing the data and allowing users to navigate between pages and to set filters. The report is shown only to users who have permission to view the report in Power BI. All row level security (RLS) rules are also applied. Lastly, the user needs to be correctly licensed – either they need a Power BI Pro license, or the report must be in a workspace that is in a Power BI Premium capacity.
When using the iFrame option, it is best to edit the HTML provided to specify the desired height and width to fit into your portal’s web page.
Granting access to reports
The Embed option does not automatically give users permission to view the report. The permissions to view the report are set within the Power BI service.
To provide access to the report within the Power BI service, you can share the report with the users who require access to the embedded report. If you are using an Office 365 Group, you can list the users as a member of the app workspace within the Power BI service. For more information, see how to manage an app workspace.
Licensing
Users viewing the embedded report need either a Power BI Pro license or the content needs to be in a workspace that’s in a Power BI Premium capacity (EM or P SKU).
Customizing your embed experience using URL Settings
The ability to create experiences without advanced coding skills, what’s know as low-code, is truly special with this capability.
The embed URL supports several input settings that help you customize your user’s experiences. If you’re using the HTML snippet provided, make sure you update the URL in the iFrame’s src setting.
| Property | Description |
| pageName | You can use the pageName query string parameter to set which page of the report to open. The pageName value corresponds to the end of the report URL when viewing a report in the Power BI Service, as shown below. |
| URL Filters | You can use URL Filters in the embed URL you received from the Power BI UI to filter the content of the embed. This can be used to build low-code integrations with only basic HTML and JavaScript experience. |
How to set which page to open when the report is embedded
The value provided in the pageName setting corresponds to the end of the report URL when viewing a report in the Power BI Service.
Open the report from the Power BI service in your web browser, and then copy the URL from the address bar.
Append the pageName setting to the URL as follows:
How to filter report content using URL filters
For some advanced features, you can URL Filters to build more experiences using the report. For example, the URL below filters the report to show data for the Energy industry.
Using the combination of pageName and URL filters can be very powerful. You can build experiences using basic HTML and a rudimentary JavaScript. For example, here’s how you can add a button to an HTML page:
| HTML |
<button class="textLarge" onclick='show("ReportSection", "Energy");' style="display: inline-block;">Show Energy</button> |
When pressed, the button calls a function to update the iFrame with an updated URL which includes the filter for the Energy industry.
| JavaScript |
function show(pageName, filterValue){//Set the baseUrl to the embed url you get from the Power BI UIvar newUrl = baseUrl + "&pageName=" + pageName;if(null != filterValue && "" != filterValue){/code>newUrl += "&$filter=Industries/Industry eq '" + filterValue + "'";}//Assumes there’s an iFrame on the page with id="iFrame"var report = document.getElementById("iFrame");report.src = newUrl;} |
You can add as many buttons as you’d like to create a low-code custom experience. The example shows a completed experience using this technique.
Limitations:
- The user will need to sign-in to view the report whenever they open a new browser window.
- Some browsers require you to refresh the page after sign-in, especially when using InPrivate or InCognito modes.
- To achieve a single sign-on experience, use the Embed in SharePoint Online option, or build a custom integration using the User Owns Data approach. Learn more about User owns data
- The automatic authentication capability provided with the Embed option does not work with the Power BI JavaScript API. For the Power BI JavaScript API, use the User Owns Data approach to embedding. Learn more about User owns data
- Secure embed does not support paginated reports or dashboards.
- Embedding in Portals for Azure B2B users is not yet supported.
When should I use the new Embed option instead of other options like Embed in SharePoint Online, Publish to web, or user owns data?
The new Embed option allows you to securely embed reports from Power BI in portals that do not have a native integration with Power BI, for example with SharePoint 2019. Use it whenever you need to embed in a web portal and you need to keep the data in the report secure.
If you’re using SharePoint Online, we recommend you use the Power BI web part in conjunction with the Embed in SharePoint Online option. This will give you a better experience than just using the Embed option, including single sign-on, more control over the embedded content.
If you want to make you report public and embed it in a public website then Publish to web is the right option. Publish to web should never be used with confidential or proprietary data.
The User owns data approach is for developers seeking to have complete control over their embedded report experience, it requires more technical skill to accomplish. Because it supports the Power BI JavaScript API, developers can implement stunning experiences within their own applications or portals.
Next Steps:
Learn more about secure Embed
Learn more about Embed in SharePoint Online
Learn about User owns data
Learn more about URL Filters