Use app-only token

[THIS IS PRELIMINARY DOCUMENTATION AND CURRENTLY UNDER REVIEW]

Usage Starting with v9.5 an administrator can configure a second Azure AD App registration. The permissions that you assign to this app will then be used by the plugin and there is no need to have these permissions statically assigned to the signed-in user. In other words, those permissions can then be removed from the primary Azure AD App registration. Doing so eliminates the need for sensitve permissions such as Groups.Read.All and User.Read.All being granted for all users.

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

Permissions needed by the plugin

User Delegated permissions

User.Read | Sign in and read user profile

  • Description Allows users to sign-in to the app, and allows the app to read the profile of signed-in users. It also allows the app to read basic company information of signed-in users.
  • Usage To enable Single Sign-on. Mandatory for all plugin editions.
  • Must be assigned to the primary Azure AD App registration.

email | View users’ email address

  • Description Allows the app to read your users’ primary email address.
  • Usage To allow the plugin to request the user’s email address as part of the authentication response (= Open Connect ID token). Mandatory for all plugin editions.
  • Must be assigned to the primary Azure AD App registration.

openid | Sign users in

  • Description Allows users to sign in to the app with their work or school accounts and allows the app to see basic user profile information
  • Usage To enable Single Sign-on (through Open Connect ID). Mandatory for all plugin editions.
  • Must be assigned to the primary Azure AD App registration.

profile | View users’ basic profile

  • Description Allows the app to see your users’ basic profile (name, picture, user name).
  • Usage To enable Single Sign-on. Mandatory for all plugin editions.
  • Must be assigned to the primary Azure AD App registration.

offline_access | Access user’s data anytime

  • Description Allows the app to read and update user data, even when they are not currently using the app.
  • Usage In October 2018 Microsoft changed their Azure AD token endpoint and it was no longer possible to request more than one access token on behalf of a user using the authorization code (obtained by the plugin initially when the user signs in with Microsoft). According to the Microsoft documentation it was only possible to request more than one access token by sending a refresh token. However, a refresh token would only be issued when the administrator has added and granted the offline_access permission. However, one year later the documentation is not very clear on when a refresh token is issued and the plugin and its features seem to work fine without it.
  • Must be assigned to the primary Azure AD App registration.

SharePoint – Sites.Search.All | Run search queries as a user

  • Description Allows the app to run search queries and to read basic site info on behalf of the current signed-in user. Search results are based on the user’s permissions instead of the app’s permissions.
  • Usage To allow the plugin to search items in on behalf of the current signed-in user. Mandatory for all versions of the plugin if you are planning on rolling out the Content by Search app.
  • Must be assigned to the primary Azure AD App registration if you are planning on rolling out the Content by Search app.

User Delegated or Application permissions

User.Read.All | Read all users’ full profiles

  • Description Allows the app to read the full set of profile properties, reports, and managers of other users in your organization, on behalf of the signed-in user.
  • Usage To allow the plugin to synchronize users between Office 365 / Azure and WordPress. Mandatory for all versions of the plugin if you are planning on rolling out the Employee Directory app. Also mandatory for the PREMIUM and INTRANET editions of the plugin, provided that you are going to enable the User synchronization feature.
  • Must be assigned to the primary Azure AD App registration if you are planning on rolling out the Employee Directory app . However, if you opted to Use an app-only token and you are not planning to roll out the Employee Directory app then you should assign this permission to the secondary Azure AD App registration as an application permission (instead of a delegate permission).

Group.Read.All | Read all groups

  • Description Allows the app to list groups, and to read their properties and all group memberships on behalf of the signed-in user. Also allows the app to read calendar, conversations, files, and other group content for all groups the signed-in user can access.
  • Usage To allow the plugin to map between Office 365 / Azure AD group memberships and WordPress roles. Mandatory for the PREMIUM and INTRANET editions of the plugin, provided that you are going to implement role based access using Office 365 / Azure AD groups.
  • Can be assigned to the primary Azure AD App registration. However, if you opted to Use an app-only token then you should assign this permission to the secondary Azure AD App registration, however, as an application permission (instead of a delegate permission).

Sites.Read.All| Read items in all site collections

  • Description Allows the app to read documents and list items in all site collections on behalf of the signed-in user.
  • Usage To allow the plugin to read documents and list items as stated.
    Mandatory for all versions of the plugin if you are planning on rolling out the Documents app. Optionally, the WPO365 Wizard app may require this permission as well to help you determine your SharePoint home URL when you (try to) configure the Content by Search (SharePoint Online) shortcode generator. However, if this permission is missing you can manually enter your SharePoint home URL.
  • Must be assigned to the primary Azure AD App registration if you are planning on rolling out the Documents app.