Embed a report in a secure portal or website

With the new Embed option for Power BI reports, you can easily and securely embed reports in internal web portals. These portals can be cloud-based or hosted on-premises, such as SharePoint 2019. Embedded reports respect all item permissions and data security through row-level security (RLS). They provide no-code embedding into any portal that accepts a URL or iFrame.

The Embed option supports URL Filters and URL settings. It allows you to integrate with portals using a low-code approach requiring only basic HTML and JavaScript knowledge.

How to Embed Power BI reports into portals

  1. The new Embed option is available on the File menu for reports in the Power BI service.

    Secure Embed option drop-down option

  2. Select the Embed option to open a dialog that provides a link and an iFrame you can use to embed the report securely.

    Embed option dialog box

  3. Whether a user opens a report URL directly, or one embedded in a web portal, report access requires authentication. The following screen appears if a user has not signed-in to Power BI in their browser session. When they select Sign-In, a new browser window or tab could open. Have them check for pop-up blockers if they don't get prompted to sign in.

    Sign in to view this report

  4. After the user has signed in, the report opens, showing the data and allowing page navigation and filter setting. Only users who have view permission can see 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. The user needs to sign in each time they open a new browser window. However, once signed in, other reports load automatically.

    Embed report

  5. When using an iFrame, you may need to edit the height and width to have it fit in your portal’s web page.

    Set height and width

Granting report access

The Embed option doesn't automatically permit users to view the report. View permissions are set in the Power BI service.

In the Power BI service, you can share embedded reports with users requiring access. If you're using an Office 365 Group, you can list the user as a workspace member. For more information, see how to manage your workspace in Power BI and Office 365.

Licensing

To view the embedded report, users 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).

Customize your embed experience using URL settings

You can customize the user experience using the embed URL's input settings. In the provided iFrame, you can update the URL's src settings.

Property Description
pageName You can use the pageName query string parameter to set which report page to open. You can find this value at the report URL's end 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 embed content. This way you can build low-code integrations with only basic HTML and JavaScript experience.

Set which page opens for an embedded report

You can find the pageName value at the report URL's end when viewing a report in the Power BI service.

  1. Open the report from the Power BI service in your web browser, and then copy the address bar URL.

    Report section

  2. Append the pageName setting to the URL.

    Append pageName

Filter report content using URL filters

You can use URL Filters to provide different report views. 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 powerful. You can build experiences using basic HTML and JavaScript.

For example, here’s a button you can add to an HTML page:

<button class="textLarge" onclick='show("ReportSection", "Energy");' style="display: inline-block;">Show Energy</button>

When selected, the button calls a function to update the iFrame with an updated URL, which includes the Energy industry filter.

function show(pageName, filterValue)

{

var newUrl = baseUrl + "&pageName=" + pageName;

if(null != filterValue && "" != filterValue)

{

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;

}

Filter

You can add as many buttons as you’d like to create a low-code custom experience.

Considerations and limitations

  • Paginated reports are supported with secure embed scenarios, and paginated reports with URL parameters are also supported. Read more about passing report parameters in a URL for a paginated report.

  • Doesn't support external guest users with Azure business to business (B2B).

  • Secure embed works for reports published to the Power BI service.

  • The user needs 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 embedding method.

  • The automatic authentication capability provided with the Embed option doesn't work with the Power BI JavaScript API. For the Power BI JavaScript API, use the user owns data embedding method.

  • The authentication token lifetime is controlled based on your AAD settings. When the authentication token expires, the user will need to refresh their browser to get an updated authentication token. The default lifetime is one hour, but it could be shorter or longer in your organization.

Next steps