Microsoft Graph Permissions Required by Employee Directory

Introduction

The Vitextra Employee Directory solution does not keep an employee database of its own. People, profile attributes, photos, managers, Teams presence and free/busy information are read at run time from Microsoft 365 through the Microsoft Graph API. For that, the solution package requests five Microsoft Graph permissions, which a tenant administrator approves once.

This article lists the permissions, explains what each of them is used for and which web part needs it, describes exactly what users see when a permission is not approved, and shows how to approve the permissions and check their status. It is intended for SharePoint and Microsoft 365 administrators and for security reviewers who assess the product before deployment.

The permissions

The Vitextra Employee Directory package contains three web parts - Employee Directory, Employee Directory (Entra ID) and New Employees - and requests one set of permissions for all of them. All five are delegated permissions for Microsoft Graph:

Employee Directory uses these permissions only to read directory, profile and mailbox data in Microsoft Entra ID and Microsoft 365. It does not modify those data or request permissions with Write in their names. Saving web part settings on a SharePoint page is separate from these Microsoft Graph permissions.

Delegated, not application permissions

All five permissions are delegated: every call to Microsoft Graph is made from the browser of the signed-in user, with a token issued for that user. The web parts have no application (app-only) permissions, no service account and no back-end of their own that reads your directory.

Microsoft Graph evaluates the granted delegated scopes together with the signed-in user’s rights. The directory may therefore differ from the people visible in Outlook or Teams; it is not a copy of their address books.

The User Profiles source and SharePoint search

The Employee Directory web part can read people from two sources, selected in its settings:

• Entra ID (Azure AD) - the list, search and paging go through Microsoft Graph and depend on the permissions above.
• User profiles - the list, search, refiners and sorting come from SharePoint search (the People results of the SharePoint search service), not from Microsoft Graph. They work under the user's own SharePoint search rights with the usual security trimming and need none of the Microsoft Graph permissions. The Recent Documents section of the details pane also uses SharePoint search.

Even with the User profiles source, some parts of the web part still call Microsoft Graph: photos, presence and the Out of Office message, the Manager and Direct Reports sections and the Local time, Working hours and Availability section in the details pane, as well as the My team and People I work with quick filters. They depend on the same permissions as in the Entra ID (Azure AD) mode.

The Employee Directory (Entra ID) and New Employees web parts always use Microsoft Graph.

What users see when a permission is missing

The web parts are designed so that a missing optional permission removes only the dependent feature. The exact behavior, as implemented in the current version:

Approving the permissions

The permission requests are created automatically when the Employee Directory package is deployed to the tenant App Catalog. A Global Administrator approves them:

1. Open the SharePoint admin center.
2. In the left navigation, expand Advanced and select API access.
3. On the Pending requests tab, find the requests of the Vitextra Employee Directory package for Microsoft Graph - Directory.Read.All, User.Read.All, Presence.Read.All, Calendars.Read and People.Read.
4. Select each request, click Approve and confirm.

Users get no consent prompt: after the approval the web parts work for everybody in the tenant. If a web part still shows an error a few minutes after the approval, reload the page.

Checking the status of the permissions

To check which permissions are in place, open Advanced › API access in the SharePoint admin center:

• The Approved requests tab must list all five Microsoft Graph permissions. Because the grants are tenant-wide, a permission may be listed there under another package that requested it first - that is enough.
• Any permission still listed on the Pending requests tab is not yet in effect; the features that depend on it behave as described in What users see when a permission is missing.

When you update Employee Directory, the permissions approved earlier stay approved. If a new version requests an additional permission, it appears on the Pending requests tab and must be approved in the same way.

Notes for security reviews

For a security review, these points are usually relevant:

• All five Microsoft Graph permissions are delegated and read-only; they do not allow Employee Directory to modify directory, profile or mailbox data.
• Directory data, photos, presence and calendar information are requested by the user's browser directly from Microsoft Graph and SharePoint and are not sent to Vitextra or to any third party.
• The User profiles source reads people through SharePoint search under the user's own rights and needs no Microsoft Graph permission for the list itself.
• Favorites, the cached employee list and the default configuration of the Teams personal app are stored outside Microsoft Graph; where exactly, and what data the web parts read, is described in KB10469. Employee Directory: What Data It Reads and Where Favorites and Settings Are Stored.
• Requests to Vitextra services include license checks, usage telemetry with technical identifiers and, when used, storage of the Teams personal-app default configuration; see KB10363. Where Vitextra Products Store Your Data: Privacy, Data Residency and GDPR.

Learn more about the product: https://vitextra.com/en/products/employee-directory