Enable integration with Microsoft Services

Use this guide if you want to configure the integration capability of the WordPress + Office 365 plugin for it to be able t request access tokens needed to request data from Microsoft Services such as Microsoft Graph, SharePoint Online and Power BI (also see the following video https://youtu.be/0gUd5LUmgag).

Introduction

To enable integration with Microsoft Services such as Yammer, SharePoint Online and Power BI you must enable WordPress (with the help of the WPO365 | LOGIN plugin) to 

• Either authenticate and authorize the currently logged-in user (= delegated access)
• Or authenticate and authorize itself without a logged-in user present (= application access).

Enabling the WPO365 plugin to integrate with Microsoft Services can be achieved in five steps.

1. Registering your application (= WordPress website) in Azure AD by creating an App registration.
2. Allow it to issue access tokens (= authorization that must be presented each time data is requested from a Microsoft Service).
3. Grant (API) Permissions (= configure the API endpoints that may be accessed with the access token).
4. Create a Client secret (= effectively the password that you must sent along together with the App registration's Application (client) ID when requesting an Access token).
5. Update the plugin's configuration to connect to the App registration. 

Before you start

• 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.

Step 1 - App registration

If you already configured the Single Sign-on capability of the plugin then you already created an App registration in Azure AD. Go to WP Admin > WPO365 > Single Sign-on and click the link View in portal to view the App registration in Azure Portal.

If you haven't yet created an App registration e.g. because you do not intend to configure the Single Sign-On then please create one and perform the following steps.

• 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.
• Click + New registration.
• On the Register an application page appears, enter your application’s registration information.
  • Name Enter a meaningful application name that will be displayed to users of the app.
  • Supported account types Select which accounts you would like your application to support (most likely Accounts in this organizational directory only)
  • Platform configuration (Optional) Do not select a platform
• Click Register to create the App registration in Azure AD.

Please not that if you intend to configure Single Sign-on that you must do that first and then come back to enable the integration with Microsoft Services and use the App registration you created to enable Single Sign-on.

Step 2 - Configure implicit grant

Important Only allow if you selected Hybrid Flow instead of Auth.-code flow (recommended) as the OpenID Connect Flow on the plugin's Single Sign-on page.

Please read this article to better understand why it is recommend - starting with version 18 of the WPO365 plugin - to select the Authorization Code Flow.

Perform the following steps to allow the App registration to issue tokens to the browser (hybrid flow).

• Navigate to your App registration from the previous step.
• Click Authentication from the 'App registration' menu on the left.
• Scroll down to Implicit grant and check Access tokens (used for implicit flows) for the plugin to request such tokens from Microsoft.

Step 3 - API Permissions

• Navigate to your App registration from the previous step.
• Click API permissions from the 'App registration' menu on the left.
• Now click + Add permission and add permissions using the table below that declares the required permissions on a per feature base.
• Once you have added all necessary permissions you must click Grant admin consent for your tenant.

Please note that all permissions in the previous table are Microsoft Graph permissions, unless indicated differently.

Note the difference between Delegated permissions and Application permissions when adding permissions.

All permissions to support all features offered by WPO365 plugins, extensions and bundles.

Before you continue to step 4, make sure that you have clicked Grant admin consent for your tenant or else the integration will not work as expected.

Step 4 - Certificates & Secrets

• Click Certificates & Secrets from the 'App registration' menu on the left.
• Click + New client secret.
• Optionally you can give the new secret a name that helps you remember it later and choose an expiry date e.g. 24 Months.
• Copy the secret's Value (not its ID) and temporarily paste it in a text file as soon as you save it. You won’t be able to retrieve it later.

Step 5 - Plugin configuration

• Navigate to the Integration page of the plugin’s wizard and paste the Application (client) secret that you created in the previous step in the corresponding field in the Delegated access section.
• If you have configured any application permissions during Step 3 - API Permissions then you must scroll down to the Application access section and perform the following steps.
  • Check the option to Use App-only token.
  • Also check the option immediately below it to Use existing App registration.

Please note that it is also possible to create a 2nd App registration to keep delegated and application permissions separated. In an attempt to simplify things, however, it is now recommended (and supported by the plugin starting with version 15.2) to use only 1 App registration. If you still would like to create a 2nd App registration you can follow the steps explained in Step 1 - App registration.

• Select your preferred Microsoft Graph version (recommended is Beta).
• Enable WPO365 API for Microsoft Graph if you are planning on implementing any of the following:
  • WPO365 User synchronization
  • Power BI (an app to embed Power BI content in WordPress using a shortcode based app)
  • Content by Search (an app to embed a SharePoint Online Search experience in WordPress using a shortcode based app)
  • Documents app or Block (an app to embed a SharePoint Online Library or OneDrive Library in WordPress using a shortcode based app)
  • Employee Directory (an app to embed an Azure AD based Employee Directory in WordPress using a shortcode based app)
  • Yammer (an app to embed a Yammer feed in WordPress using a shortcode based app)

The exact configuration of the  Microsoft 365 Apps section depends on the feature / app that you are planning to implement and will be explained in the corresponding implementation guide for the feature / app.

Note that if you’re still using a version before v17.0 of the plugin you must enable the Token service and Check nonce for improved security.

• Click Delete tokens to ensure that all existing access tokens are deleted and any changes you made are reflected by new fresh tokens retrieved from the Azure AD endpoint.

Plugin self-test

Perform the following steps to check your configuration.

• Click Plugin self-test from the plugin's wizard menu.
• Click Start self-test to check the current configuration and the plugin’s ability to retrieve a valid  access token.

As soon as the self-test is starting, the ‘Test mode’ will be activated. During this time the plugin is not protecting your website. The plugin will now try and sign in using Microsoft and you may be prompted by Microsoft to sign in. Please be aware that at no time your authentication input will be shared with (y)our website and or the plugin: All information you enter is only shared with Microsoft at all times!

• Once the self-test is finished (during the self-test the page may be reloaded) you will see the test results. You can click on each entry in the list to view the full details incl. category, severity and a proposed resolution to fix the issue.