Microsoft Power BI for WordPress

Use this guide, if you want to embed a Microsoft Power BI report, dashboard or tile in a WordPress page or post (also see the following video https://youtu.be/fDyB_Ue72j4). Also make sure to visit https://www.wpo365.com/power-bi-for-wordpress/ for details how you can unlock premium features such as support for the App owns data scenario, adding custom report filters, defining custom settings e.g. to hide a panel and support for row-level security (RLS).

Before you start

• You must already have configured the single sign-on capability of the WordPress + Office 365 plugin.
• Additionally, you must also already have configured the integration capability of the plugin.

• You are a Global Administrator for your company’s Office 365 tenant / Azure AD directory (or have at least the ability to edit the Azure Active Directory App registration that was created previously when the single sign-on capability was configured).
• You are an Administrator for your WordPress website.

Choosing a scenario

Embedding Power BI content into a WordPress page or post with the help of the WPO365 plugin (and extensions) can be done in one of two ways.

User owns data In this case the user has been given access to the Power BI workspace in question. Therefore the user must sign in with Microsoft (with the help of the WPO365 plugin) to your WordPress website. This is necessary so the plugin can obtain an access token for Microsoft Graph to access the Power BI REST APIs. This also implies that you must configure the appropriate delegated permissions (see API Permissions below).

Application owns data In this case the user has not been given access to the Power BI workspace in question. Instead the Service Principal (= App registration) that you created when you configured the single sign-on capability of the WPO365 | LOGIN plugin must be given administrative access to the Power BI workspace in question (see Prepare your Power BI environment below).

Considerations and Limitations

• Ensure that you have selected the Beta version for the Microsoft Graph on the plugin's Integration page.
• SAML 2.0 is not supported in combination with the User owns data scenario.
• The Application owns data is not available for the basic version of the Power BI Embed app but instead requires the WPO365 | M365 APPS or the WPO365 | INTRANET bundle to be installed and activated. 
• Please make sure that you have read the considerations and limitations section on the Microsoft website.
• Disclaimer According to Microsoft - in case of the Application owns data scenario - a capacity is required when moving to production. Recently Microsoft has started showing the following banner for users that did not purchase such a capacity

And added a link to the following Move to production documentation: https://docs.microsoft.com/en-us/power-bi/developer/embedded/move-to-production.

App registration

• In Azure Portal click the 'hamburger' (icon with three horizontal lines in the upper corner) to open the menu.
• Navigate to Azure Active Directory > App registrations.
• Select the App registration that you created when you configured the single sign-on capability of the plugin.

API Permissions

Please note If you intend to implement the Application owns data scenario there is not need to assign delegated permissions and you can skip this step.

• Click API permissions from the 'App registration' menu on the left
• Click + Add permission.
• Select Power BI Service > Delegated permissions.
• Scroll down to Dataset and check
  • Dataset.Read.All
• Scroll down to Report and check
  • Reports.Read.All
• Click  Add permissions.
• Click Grant admin consent for … to grant consent for all users in your tenant to use this ‘App registration’.

Depending on your requirements you can of course add more permissions e.g. Workspace.Read.All, Dashboard.Read.All.

Integration

• Navigate to WP Admin > WPO365 > Integration.
• Scroll down to the section labelled Microsoft 365 Apps.
• Check the option to Enable WPO365 API for Microsoft Graph.
• If you are implementing a user-owns-data scenario you must require users to Sign in with Microsoft.
• Alternatively, if you are implementing an application-owns-data scenario users are not required to sign in with Microsoft or sign in at all. Please be aware that if you do not require your users to sign in at all that you expose the API to anonymous users and this is really not recommended.
• Add https://api.powerbi.com/ to the list of Allowed endpoints.
• Check the option so Apps may request (delegated) oauth access tokens.
• Check the option to Enable Microsoft Graph proxy-type requests.

Prepare your Power BI environment

Important 

• The WPO365 plugin only supports the embedding of Power BI content using a Service principal. Authentication using a master account is not supported. This also means that content must reside in new workspaces (and that traditional workspaces are not supported).
• You should not register a new App in Azure AD. Instead you can use the existing App registration (= Service Principal) that you registered initially when you configured the single sign-on feature and possible other integrations e.g. with SharePoint Online, Yammer etc.
• You must, however, configure your Power BI environment to support Service principal authentication. Using this method that can be used to let an Azure AD application access Power BI service content and APIs. To do so, please carefully execute the following steps documented by Microsoft (see https://docs.microsoft.com/en-us/power-bi/developer/embedded/embed-service-principal):
  • Create an Azure AD security group
  • Once you created the Azure AD security group, copy the Application (client) ID (from the plugin's Single Sign-On page) and add this user to the new Azure AD security group.
    • Navigate to the Azure AD security group in your Azure Portal.
    • Click Members.
    • Click + Add members.
    • Paste the Application (client) ID and click the Service Principal from the results to select it.
    • Click Select to add the Service Principal to the group.
  • Enable the Power BI service admin settings
  • Add the service principal as an admin to your workspace
  • Embed your content

When you see an error that states "... No authorization code and refresh token found when trying to get an access token for https://graph.microsoft.com/User.Read. The current user must sign out of the WordPress website and log back in again to retrieve a fresh authorization code that can be used in exchange for access tokens ..." Then please sign out of your WordPress website and immediately sign back in (with Microsoft) into your site. This will ensure that the plugin retrieved a fresh set of access tokens on your behalf.

Generate a Microsoft Power BI shortcode

The table below provides a simple overview of the available features per plugin edition.

To generate a shortcode to embed a Microsoft Power BI artifact into any WordPress page or post, perform the following steps. 

• Navigate to WP Admin > WPO365 > ... > Power BI.
• Select the Microsoft Power BI artifact to embed i.e. report, dashboard or tile.
• Select the desired token type:
  • For the User owns data scenario select the AAD Token.
  • For the Application owns data scenario select the corresponding (type of) Embed Token (the shortcode generator will only enable those options that match with the Microsoft Power BI artifact that you want to embed e.g. Report in Workspace and Multiple Items when you want to embed a Report.
• Enter the Workspace ID of the Microsoft Power BI Workspace where the artifact that you are embedding resides in.
• Then
  • Enter the Report ID of the Microsoft Power BI report if you are embedding a report.
  • Enter the Dashboard ID of the Microsoft Power BI dashboard if you are embedding a dashboard.
  • Enter the Dashboard ID and the Tile ID of the Microsoft Power BI tile and its containing dashboard if you are embedding a tile.

Please note that you can find all these IDs when you navigate to https://app.powerbi.com/ and then load the workspace of your choice. In your workspace open the artifact that you want to embed. Once open, the web address should contain all necessary IDs. The following URL is an example for a report with ID 206e6e12-b5f6-4542-a22e-2c17de272a4f in a workspace with ID f6fddbde-2415-435a-9c51-e8d6a2b6274b e.g. https://app.powerbi.com/groups/f6fddbde-2415-435b-9c51-e8d6a2b6274b/reports/206f6e12-b5f6-4542-a22e-2c17de272a4f/ReportSectionb4bd8f0e6c0029bcea0b. 

• Finally you can enter the height and width of the embedded artifact on your WordPress page.
• Click Copy shortcode to clipboard.

Embed a Microsoft Power BI artifact in a WordPress page or post

• From the WordPress Admin Bar, click + New to add a new WordPress page or post.
• On the page or post, type shortcode in the block navigator and click the shortcode shortcut to add a new shortcode block to the page or post.
• In the shortcode editor, click Ctrl+V (or right mouse click and click Paste) to paste the shortcode.
• Publish the page and then click View post to check the result.

Advanced (premium-only) configuration options

If you'd like to take more control over how your Power BI report is embedded, you can click to manually edit the embed config (JSON) as shown below.

Adding custom Report Settings

Editing the configuration manually allows you to add settings e.g. to collapse the filters panel, as shown in the previous image and example below.

...
"settings": {
      "panes": {
          "filters": {
              "expanded": false,
              "visible": true
          }
     }
},
...

You can have a look at this article to learn more embedded Power BI report settings.

Adding Report Filters

Also visible in the previous image is a configuration that would add a filter to your report. Again, this can be achieved if you manually edit the configuration and add a filter configuration as shown below.

{
  "$schema": "http://powerbi.com/product/schema#basic",
  "target": {
    "table": "Sales",
    "column": "Country"
  },
  "operator": "In",
  "values": ["Canada"],
  "filterType": 1,
  "requireSingleSelection": true
}

When editing a filter configuration you must convert some enumerated values into number. In the example above you'll notice that filterType is set to 1. To look up those enumerated values you can use the Power BI models reference. Here you can search for the actual values for filterType only to find that 1 stands for Basic.

Please note that configuration properties must follow the JSON notation and all must be wrapped in double quotes e.g. "filterType".

Support for RLS

Row-level security (RLS) can be used to restrict user access to data within dashboards, tiles, reports, and datasets. Different users can work with those same artifacts all while seeing different data. Embedding supports RLS. Read more ...

If you're embedding to Power BI users (user owns data), within your organization, RLS works the same as it does within the Power BI service directly. There's nothing more you need to do in your application. For more information, see Row-Level security (RLS) with Power BI.

If you're embedding for non-Power BI users (app owns data), which is typically an ISV scenario, then you must configure the embed token so it is issued for an Effective Identity (a user and one or more roles).

By default the  Token request JSON (for non-Power BI / app owns data) is as follows.

{
  "accessLevel": "View"
}

{
  "accessLevel": "View",
  "identities": [
        {
            "username": "ellen@wpo365.com",
            "roles": [ "Canada" ],
            "datasets": [ "795b2d57-22d6-4c08-9db3-b660fe9b3483" ]
        }
    ]
}

• Use direct user attributes by combining the prefix wp_ with a WP_User object's property name e.g. wp_user_email
• Use user meta attributes by combining the prefix meta_ with the WordPress user meta key's name e.g. meta_power_bi_roles

{
  "accessLevel": "View",
  "identities": [
        {
            "username": "wp_user_email",
            "roles": "meta_power_bi_roles",
            "datasets": [ "795b2d57-22d6-4c08-9db3-b660fe9b3483" ]
        }
    ]
}

To add user meta to a user's profile we used two plugins from Meta Box (see https://metabox.io/) to allow a user administrator to define Power BI roles for WordPress users.
With (the premium plugin) MB User Meta installed we just needed to add the following PHP snippet to our WordPress (child) theme's functions.php.

add_action('rwmb_meta_boxes', function ($meta_boxes) {
    $meta_boxes[] = array(
        'title' => 'Power BI Roles',
        'type'  => 'user', // THIS: Specifically for user


        'fields' => array(
            array(
                'name'     => 'Power BI Roles',
                'id'       => 'power_bi_roles',
                'type'     => 'select_advanced',
                'multiple' => true,
                'options' => array(
                    'Canada' => 'Canada',
                    'Germany' => 'Germany'
                ),
            ),
        ),
    );
    return $meta_boxes;
});

This example renders an easy-to-use custom user profile field to edit a user's Power BI roles.

Please note that this is just an example how we were able to add custom user meta to a user's WordPress profile and that this is not a recommendation.

Add your own JavaScript (for developers)

Many customers have asked whether they can manipulate the embedded content themselves directly using JavaScript. This is possible. The following code is a simplified example of how you can wait for the powerbi object to become available in the global window namespace and then toggle a report's fullscreen mode.

var reportLoaded = window.setInterval(() => {
	if (window.powerbi && Array.isArray(window.powerbi.embeds)) {
		window.clearInterval(reportLoaded);
		window.powerbi.embeds[0].fullscreen();
	}
}, 100);

Happy coding!

Troubleshooting