App-only Integration

Introduction

Use this guide if you want to assign app-only permissions to the WordPress + Microsoft Office 365 / Azure AD plugin (also see the following video https://youtu.be/bc7703fe6lo).

App-only permissions are so-called application permissions that do not require a logged-in user. With app-only permissions the plugin can get authorization to access - for example - Microsoft 365 services (using OAuth 2.0) instead of a user. That the plugin - instead of a user - can get authorization to access Microsoft 365 services can be an advantage in the following cases:

• If you want to use SAML 2.0 based single sign-on and you need to integrate with Microsoft Graph e.g. to retrieve custom user profile fields and images and map those to WordPress and / or BuddyPress (extended) profile fields and avatars, or to retrieve all (Azure AD and Microsoft 365) groups a user is a member of e.g. to map to WordPress or itthinx Groups then you must configure app-only permissions.
• If you want to synchronize users from Azure AD to WordPress on-the-fly (see https://www.wpo365.com/synchronize-users-between-office-365-and-wordpress/ for details) you have the choice to either assign the permission User.Read.All and Group.Read.All to all users or only to the plugin.
• If you want to schedule user synchronization then you must configure app-only permissions.
• When you configure Azure AD User provisioning (SCIM) then you must configure app-only permissions (see https://docs.wpo365.com/article/59-wordpress-user-provisioning-with-azure-ad-scim for details).

PLEASE READ CAREFULLY BEFORE YOU CONTINUE

Using app-only permissions requires you to create a new App registration in Azure AD to solely serve the purpose of granting app-only permissions to the WPO365 plugin. If you did configure SAML 2.0 based single sign-on, this new App registration will be the first App registration. However, if you did configure OpenID Connect based single sign-on (which is the default option), this new App registration will be the second App registration. In that case you already created a first App registration to configure OpenID Connect and added some delegated permissions.

To better understand the concept behind (delegated and application) permissions and consent, please review this article published by Microsoft.

When you intend to deploy the Microsoft 365 Apps that ship as part of the plugin e.g. for Power BI, Content by Search (SharePoint Online), Documents (SharePoint Online / OneDrive) and Employee Directory (Microsoft Graph) then it is important that to know that you must assign the required permissions as delegated permissions. These apps always require a logged-in user and from this it also follows that you cannot use these apps if you configured SAML based single sign-on.

Before you start

• You must already have configured the single sign-on capability of the WordPress + Office 365 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.

(App-only) 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.
• 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 secondary App registration in Azure AD.
• select API permissions and then + Add permission.
• Depending on your requirements, select Microsoft Graph and then Application permissions, scroll down and add
  • Group.Read.All
  • User.Read.All
  • Mail.Send
• Select Add permissions to save the permissions just added.
• Wait 10 seconds and then click Grant Admin consent for [your tenant].
• Select Certificates and secrets and click + New client secret.
• Enter a meaningful Name for you app’s secret and select the period during which the secret should remain valid.
• Click Add to create the new Client secret and then copy it.

Plugin configuration

• Don't close the Azure Portal tab but instead open a new browser tab.
• Navigate to WP Admin > WPO365 > Integration.
• Check Use app-only token.
• Paste the Client secret you previously copied as (App-only) Client secret.
• In the Azure Portal tab, navigate back to the Overview page and move your mouse over the Application (client) ID and click Copy to clipboard.
• Switch back to the WPO365 Integration configuration page open and paste the Application (client) ID you just copied as (App-only) Application (client) ID.

Plugin self-test

• Cick Plugin self-test from the plugin's configuration menu.
• Click Start self-test to check the current configuration and the plugin’s ability to retrieve an app-only 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.