Microsoft Graph based Employee Directory

Use this guide, if you want to embed the WPO365 Microsoft Graph based Employee Directory in a WordPress page. Please note that there are two versions of this app:

  • The basic version offers a fairly simple Microsoft Graph based search for (Azure AD) users that cannot be customized.
  • The advanced version allows for the following customizations
    • Using SharePoint People Search to search for employees and benefit from the rich people search capabilities when compared to Microsoft Graph that include searching for skills, interests, past projects and other user attributes.
    • Using application-level permissions, the Employee Directory shortcode app can be configured be used by anonymous users or at least by users that did not Sign in with Microsoft.
    • Advanced queries to search in users, (transitive) members of groups and benefit from the latest Microsoft Graph tokenization as explained in this article https://developer.microsoft.com/en-us/identity/blogs/build-advanced-queries-with-count-filter-search-and-orderby/.
    • A beautiful handlebars.js template for an interactive clickable organizational chart app.
    • The ability to upload your own custom handlebars.js template.
    • Toggle auto-search so the app will search when ever it is initially loaded e.g. to dynamically show the HR, Finance or Service Desk team.

The advanced version is included in the  WPO365 | INTRANET  bundle (see  https://www.wpo365.com/downloads/wordpress-office-365-login-intranet/  for details and pricing) and the WPO365 | M365 APPS (see  https://www.wpo365.com/downloads/wpo365-microsoft-365-apps/  for details and pricing)

Before you start

  • You must already have configured the single sign-on capability of the WordPress + Office 365 plugin unless your intention is to make the advanced version of the Employee Directory app use application-level permissions.
  • 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.

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 Integration portion of the plugin.

API Permissions

  • Click API permissions from the 'App registration' menu on the left
  • Click + Add permission.
  • Select Microsoft Graph > Delegated permissions.
  • Check
    • User.Read.All
  • Click  Add permissions.
  • Click Grant admin consent for … as an administrator to grant consent for all users in your tenant to use this ‘App registration’.
If your intention is to use (the advanced version's capability to use) SharePoint People Search (instead of Microsoft Graph) then you must also add SharePoint > Delegated > Sites.Search.All permissions.

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.
  • Require that Users must be signed in with Microsoft (unless you intend to let users that did not sign in with Microsoft use the Employee Directory app).
  • 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 and do not check the box to allow application-level permissions for that endpoint (unless you intend to let users that did not sign in with Microsoft user the Employee Directory app). 
  • Optionally, if you intend to change the Microsoft Graph query - for example - to /groups/8c6ed1df-a9e6-42dc-b213-8ff8ce93af72/transitiveMembers?$count=true&$search="displayName:{searchterms}" OR "department:{searchterms}" OR "mail:{searchterms}"&$filter=accountEnabled eq true and userType eq 'member' (see example further down) then you must add https://graph.microsoft.com/v1.0/groups instead.

  • Click Save configuration.

Allow access to the WPO365 REST API for Microsoft Graph

For the app to be able to connect to Microsoft Graph it must be able to connect to the custom WPO365 WordPress REST API. This custom REST API is installed as part of the basic infrastructure provided by the WPO365 | LOGIN plugin. Perform the following steps to prevent the plugin from blocking access to this WordPress REST API.

  • Navigate to WP Admin > WPO365 > Single Sign-On.
  • Scroll down to the list of Pages freed from authentication and add /wp-json/wpo365/v1/graph (if not already added).
  • Click + to add this entry to list.
  • Scroll to the bottom of the page and click Save configuration.

Generate an Employee Directory shortcode using the basic generator

  • Navigate to WP Admin > WPO365 > ... > Employee Directory (Graph).
  • Update the translations as you see fit, for example for Dutch you could update the translations as below.
{
  "search": "Zoeken",
  "hasResults": "{0} resultaten gevonden",
  "hasNoResults": "Geen resultaten",
  "moreResults": "Meer resultaten"
}
  • Uncheck the option to display a Skype for Business (instant messaging) link instead of Microsoft Teams.
  • Click to Copy the shortcode.
  • Create a new page or post in WordPress.
  • Add a new (Gutenberg) shortcode block (alternatively insert the shortcode as Custom HTML).
  • Paste the shortcode into the input area of the Shortcode / Custom HTML.
  • Save, publish and view the page.

The basic version of the app will always use the following default query.

/users?$count=true&$search="displayName:{searchterms}" OR "department:{searchterms}" OR "mail:{searchterms}"&$filter=accountEnabled eq true and userType eq 'member'
Especially the addition userType eq 'member' may prevent the query from retrieving users from Microsoft Graph if your users are synchronized from your (on-premise) Active Directory. In that case the userType may be null. If that is the case then please consider upgrading to the advanced version and adapt the query for your custom needs as you see fit.

Generate an Employee Directory / Contacts shortcode using the advanced generator

  • Navigate to WP Admin > WPO365 > ... > Employee Directory (Graph).

  • Use SharePoint People Search (instead of Microsoft Graph) will use the very rich SharePoint People Search which will give you the opportunity to not only search for users by their name, department and email address but also search - for example - for skills, interests and past projects.
    • If you check this option you must ensure that you have granted SharePoint > Delegated > Sites.Search.All permissions for the Azure AD App registration that you created previously to enable integration with Microsoft Services (see the online documentation for detailed steps on how to accomplish this if you haven't done so already).
    • Once you check this option you must specify Your SharePoint Home URL. If you have granted Microsoft Graph > Delegated > Sites.Read.All permissions to the aforementioned App registration in Azure AD then this URL will be retrieved automatically for you. Otherwise you must specify your SharePoint tenant's Home URL yourself in the form https://your-sharepoint-tenant.sharepoint.com.
    • Last but not least can you fully customize the Request for SharePoint Search REST API. Please note that this is only recommend if you know what you're doing. A great way for customizing and testing your query can be the SharePoint Search Query Tool. You may also benefit from studying the official SharePoint search REST API overview documentation. You can use the special token {searchterms} which will be replaced by the plugin by the search keywords the user entered in the search box.
  • Alternatively, you can use the Microsoft Graph query instead. The plugin supports building advanced queries with $filter and $search (see - for example - this article for expert guidance). You can use the special token {searchterms} which will be replaced by the plugin by the search keywords the user entered in the search box. Also you may benefit from using Microsoft's Graph Explorer to test and fine-tune your query.
Default query
/users?$count=true&$search="displayName:{searchterms}" OR "department:{searchterms}" OR "mail:{searchterms}"&$filter=accountEnabled eq true and userType eq 'member'

Example query (search transitive members of an Azure AD group)

/groups/8c6ed1df-a9e6-42dc-b213-8ff8ce93af72/transitiveMembers?$count=true&$search="displayName:{searchterms}" OR "department:{searchterms}" OR "mail:{searchterms}"&$filter=accountEnabled eq true and userType eq 'member'
  • Results per page allows you to restrict the number of results displayed per page.
  • Use (Handlebars) template allows you to fully customize how the users that are returned by Microsoft Graph are rendered / presented to your users. The option to use templates has been added since v9.5 and are now the preferred way to render search results. However, you can still uncheck this option and use the legacy placeholders for primary, secondary, tertiary and meta text. Refer to the following online documentation for instructions on how to create your own fully custom Handlebars template.
  • Template (only visible when you checked Use (Handlebars) template) allows you to configure the location where the app should try and download the (custom) Handlebars template from. Please note that for reasons of security modern browsers won’t allow you to download content from other servers than your own (unless CORS has been properly set up). By default the shortcode generator proposes to use the Handlebars template that ships with the plugin.
  • Primary / Secondary / Tertiary / Meta text (only visible when you unchecked Use (Handlebars) template) allows you to connect the built-in static template’s Primary / Secondary / Tertiary / Meta text placeholders with properties of a (Microsoft Graph) user. You can refer to this Microsoft article to understand what properties are available. Read the Select properties section further down for information on how to retrieve non-default properties.
  • Try retrieve user photo tells the app to try and connect to Microsoft Graph and download a user’s Office 365 profile image to show along with the user’s information.
  • Hide Search box / Message bar / Paging will hide the corresponding elements when checked. This is especially usefull when used in combination with an Query template and Auto search.
  • Auto search tells the plugin not wait for the user to enter a search query but instead start and search immediately. This is especially useful when used in combination with a Query Template.
  • Min. input length tells the plugin to wait before executing the search query entered by the user until at least a minimal number of characters has been entered into the search box. This setting does not prevent Auto search from executing a search immediately as soon as the app has finished loading.

Then finally

  • Click to Copy the shortcode.
  • Create a new page or post in WordPress.
  • Add a new (Gutenberg) shortcode block (alternatively insert the shortcode as Custom HTML).
  • Paste the shortcode into the input area of the Shortcode / Custom HTML.
  • Save, publish and view the page.

Troubleshooting

  • If the Employee Directory app does not retrieve users at all or not all users are retrieved then please consider fine-tuning the query with the help of Microsoft's Graph Explorer. Please note that you must sign in and that you may need to grant additional permissions before you can benefit from the tool to its full extent.
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us