WPO365 REST API for Microsoft Graph

Usage WPO365 apps for Microsoft 365 created with v17.0 or later will request data from Microsoft Graph using the WPO365 REST API for Microsoft Graph. This API is the successor of the Pintra Framework (Pintra-Fx) that was published over 3 years ago and that provided a very simple but robust client API to get access tokens needed when building apps for WordPress that support Microsoft 365 scenarios, spanning across productivity, collaboration, education, people and workplace intelligence, and much more.

An important difference and improvement between the initial version of Pintra-Fx and the new WPO365 REST API is that it does not provide access tokens to the client application. Instead it receives a query for Microsoft Graph, looks up or retrieves the necessary access token for the requested scope, forwards the query to Microsoft Graph and finally and transparently returns the response to the client application.

Developers, interested in producing their own apps that integrate with Microsoft 365 should continue to read this article.

If you intend to synchronize users from Azure AD to WordPress then you must perform the following steps:

Check the option to Enable WPO365 REST API for Microsoft Graph.
Require that Users must be signed in with Microsoft (unless you will allow application-level permissions for the endpoint you will use to retrieve users e.g. https://graph.microsoft.com/v1.0/myorganization or https://graph.microsoft.com/v1.0/users).
Leave the option to Allow apps to request any Microsoft Graph endpoint unchecked (unless you know what you are doing).
Add the endpoint that you will use to retrieve users e.g. https://graph.microsoft.com/v1.0/myorganization or https://graph.microsoft.com/v1.0/users to the list of Allowed endpoints. Since the WPO365 REST API for Microsoft Graph is only used to test the user synchronization query you can decide whether or not you check the box to allow application-level permissions for that endpoint. If you do not allow it then you must ensure that you sign in with Microsoft yourself when you configure / test WPO365 user synchronization.

If you intend to embed SharePoint Online Search (Content by Search app) or embed a SharePoint Online / OneDrive Library (Documents app) in WordPress then you must perform the following steps:

Check the option to Enable WPO365 REST API for Microsoft Graph.
Require that Users must be signed in with Microsoft (unless you intend to give anonymous users access to a SharePoint Document Library as explained in this article and in this article).
Leave the option to Allow apps to request any Microsoft Graph endpoint unchecked (unless you know what you are doing).
Add your SharePoint Home URL e.g. https://[your-tenant].sharepoint.com to the list of Allowed endpoints and do not check the box to allow application-level permissions for that endpoint.
Check the option to Allow Microsoft Graph proxy-type requests.

If you intend to embed a Yammer Feed in WordPress then you must perform the following steps:

Check the option to Enable WPO365 REST API for Microsoft Graph.
Require that Users must be signed in with Microsoft.
Leave the option to Allow apps to request any Microsoft Graph endpoint unchecked (unless you know what you are doing).
Add https://www.yammer.com to the list of Allowed endpoints and do not check the box to allow application-level permissions for that endpoint.
Check the option to Allow Microsoft Graph proxy-type requests.

If you intend to embed a Microsoft Graph based Employee Directory in WordPress then you must perform the following steps:

Check the option to Enable WPO365 REST API for Microsoft Graph.
Require that Users must be signed in with Microsoft (unless you intend to give anonymous users access to your Employee Directory app as explained in this article).
Leave the option to Allow apps to request any Microsoft Graph endpoint unchecked (unless you know what you are doing).
Add https://graph.microsoft.com/v1.0/users to the list of Allowed endpoints (the version options v1.0 or beta are ignored so you can write both). Optionally you may check the box to allow application-level permissions for that endpoint if you know what you're doing.

If you intend to embed Power BI Report, Dashboard or Tile in WordPress then you must perform the following steps:

Check the option to Enable token service.

Please note that the Power BI integration has not been migrated to the new WPO365 REST API for Microsoft Graph. Also versions of the Microsoft 365 Apps older than v17.0 continue to use this older token service.

Security considerations

The WPO365 REST API for Microsoft Graph is relying on default WordPress nonces to authenticate users.

It is important to keep in mind that this authentication method relies on WordPress cookies. As a result this method is only applicable when the REST API is used inside of WordPress and the current user is logged in. In addition, the current user must have the appropriate capability to perform the action being performed. Read more ...

Since the WPO365 REST API for Microsoft Graph provides access to Microsoft 365 services such as Microsoft Graph, SharePoint Online, Yammer and more it's important to understand how you can restrict access to the API.

Enable WPO365 REST API for Microsoft Graph

If you disable the API the routes won't be available and WordPress will send a standard HTTP 404 response.

Require users to sign-in to use the WPO365 REST API for Microsoft Graph

Assuming that you have enable the WPO365 REST API for Microsoft Graph then you can restrict access to that API to users that

Signed in with Microsoft
Signed in (but not necessarily with Microsoft)
Did not sign in (anonymous internet users)

Obviously the first option is the most secure option. Users that use the API (e.g. by using one of the Content by Search, Documents, Employee Directory or Yammer Feed apps) must have signed in with Microsoft and since you can require user assignment for the application in Azure AD (see https://docs.wpo365.com/article/72-require-user-assignment-in-azure-ad) you can effectively allow / restrict access.

The second and third option are less secure - especially if any user can sign up for your website. These options may still be of interest - for example - if you want to share a SharePoint Document Library with users that do otherwise not have access to your tenant as explained in this article and in this article).

Since these users do not sign in with Microsoft, they are not able to obtain delegated permissions. They would, however, be able - under circumstances - to obtain application-level permissions. Therefore it is recommended not to assign application-level permissions to the App registration in Azure AD outside of a specific scope that you are willing to compromise.

In general it is not recommend to allow access to the WPO365 REST API for Microsoft Graph for users that did not sign in with Microsoft for scenarios other than giving non-tenant-users access to a SharePoint Document Library that you have configured for anonymous access using the special Sites.Selected permission.

Allowed endpoints

In an attempt to improve the overall security you can (and you should) restrict access only to selected Microsoft Services endpoints. Those endpoints must be entered as absolute URLs e.g. https://graph.microsoft.com/v1.0/users or https://www.yammer.com.

Allow Microsoft Graph proxy-type requests

The WPO365 REST API for Microsoft Graph provides developers with a number of default endpoints e.g. https://graph.microsoft.com/v1.0/sites and https://graph.microsoft.com/v1.0/users to retrieve sites, list items and users. Some Microsoft Services, however, have different endpoints and developers must connect - for example - to https://www.yammer.com/api or https://[your-tenant].sharepoint.com/_api/search. In those cases you must explicitly allow this type of request and you must add the allowed endpoints to the corresponding list (also see the previous screenshot).