Connect Microsoft 365

This page walks through connecting Microsoft 365 end to end. Workforce Intelligence (WI) uses an app you register in your own Microsoft Entra tenant, so people sign in with Microsoft and WI acts with their access. The general connection form, the Allow, Ask and Block defaults and who may use a connection are covered in Connecting outside systems; this page covers what is specific to Microsoft.

You need the admin ability in WI, and an Entra role that can register applications (Microsoft names Application Developer as the minimum). Granting admin consent needs a more privileged Entra role, such as Cloud Application Administrator.

Register the app in Microsoft Entra#

1. Sign in to the Microsoft Entra admin center and open Entra ID > App registrations, then select New registration.
2. Enter a Name people will recognize, such as "Workforce Intelligence".
3. Under Supported account types, choose who may sign in. Microsoft recommends Single tenant only for most apps, and that is the right choice when every person who connects belongs to your organization. See "Single tenant or multiple tenants" below, because it decides the address you enter in WI.
4. Select Register. The Overview page shows the Application (client) ID and the Directory (tenant) ID. You need both.

Add the redirect URI#

1. In WI, open Settings, select Review on the Connectors card, then Add a connection, and pick Microsoft. The form shows Redirect URI to register. Keep this page open or copy the value.
2. In your app registration, under Manage, select Authentication. On the Redirect URI configuration tab select Add Redirect URI, choose the Web platform, paste the redirect URI exactly as WI shows it, and select Configure.

The platform must be Web. A redirect URI registered under another platform type is refused.

Create a client secret#

1. Under Certificates & secrets > Client secrets, select New client secret.
2. Add a description, choose an expiry and select Add.
3. Copy the Value immediately. Microsoft shows it only once, and the Secret ID next to it is not what WI needs.

Microsoft limits a secret's life to 24 months and recommends under 12. Put a reminder in your calendar: when a secret expires, every sign-in through the connection fails until you create a new secret and paste it into the connection's Client secret field.

Add API permissions#

Under API permissions, select Add a permission, choose Microsoft Graph, then Delegated permissions, and tick the permissions below. They must be delegated permissions, because WI acts as the person who signed in. Add only what your Coworkers need; start with the read permissions.

Service in WI	Permissions to add	What they unlock
Microsoft Calendar	Calendars.Read; Calendars.ReadWrite to create, change and delete events; Calendars.Read.Shared to find meeting times	Viewing and listing events; changing events and answering invitations; suggested meeting times
Microsoft Mail	Mail.Read; Mail.ReadWrite for drafts, moving and marking; Mail.Send to send	Reading and searching mail; drafts and filing; sending, replying and forwarding
Microsoft Files	Files.Read or Files.Read.All; Sites.Read.All for SharePoint; Files.ReadWrite for writes	OneDrive and SharePoint browsing and search; creating folders and small text files
Microsoft Teams	Team.ReadBasic.All, Channel.ReadBasic.All; ChannelMessage.Read.All, ChannelMessage.Send; Chat.Read, Chat.ReadWrite	Listing teams and channels; reading and posting channel messages; reading and sending chats
Microsoft People and Tasks	People.Read, User.ReadBasic.All (or User.Read.All), Contacts.Read, Tasks.Read, Tasks.ReadWrite	People and directory lookups; contacts; To Do and Planner tasks

Also add offline_access so a connection stays active without people signing in again, and User.Read so WI can show who is connected. Entra adds User.Read for you when you register the app.

Admin consent#

Some permissions need an administrator to approve them for the organization before anyone can connect. Microsoft lists ChannelMessage.Read.All as one that does, and your organization's user-consent settings can require approval for others, Files.Read.All and Sites.Read.All among them. To approve, open API permissions and select Grant admin consent for followed by your tenant name, then confirm. The button is disabled unless you hold a suitable administrator role. A person who tries to connect before approval sees Microsoft's own request-approval screen instead of a working connection.

Single tenant or multiple tenants#

The Supported account types you chose decides which sign-in address works.

• Single tenant only (My organization only in some Microsoft screens): replace common in both the Authorize URL and the Token URL on the WI form with your Directory (tenant) ID: https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/authorize and https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token.
• Multiple tenants, or multiple tenants plus personal Microsoft accounts: the prefilled common addresses work as they are.

If the two do not match, Microsoft refuses the sign-in with error AADSTS50194.

Add the connection in WI#

1. On the Microsoft form, enter a Display name, the Application (client) ID as Client id, and the secret Value as Client secret.
2. Check the Authorize URL and Token URL (see above). Leave Profile URL as it is.
3. In the Permissions checklist, tick the same permissions you added in Entra. New connections start with the read-only defaults ticked: stay signed in, read your profile, read mail, read calendars, and read all files they can open. Ticking a permission in WI does not grant it in Entra, and the reverse is also true: both places must list it.
4. Select Add connection, then Connect on the new card and sign in with your own account.

Attach the services#

Microsoft Calendar, Mail, Files, Teams and People and Tasks share the one connection but each has its own Attach tools button and its own functions. Attach the ones you need, tick the functions to turn on and choose Allow, Ask or Block for each, as described in Connecting outside systems. A function the connection's permissions do not cover stays greyed under Needs more permissions and says which permission it needs. Send, reply and forward are the usual functions to set to Ask.

People connect their own accounts#

A Supervisor turns the connection on for each Coworker that should use it. Each person then opens Settings and connects their own Microsoft account under Connected accounts. A Coworker acts with the access of the person it is working for, so it can never reach more than that person can in Microsoft 365.

Troubleshooting#

What you see	What it means and what to do
"Microsoft refused the sign-in" with AADSTS50194	The app is single tenant but the URLs still say common. Put your Directory (tenant) ID in both URLs.
Microsoft asks for administrator approval, or sign-in fails after consent	An administrator must use Grant admin consent on the API permissions page.
The redirect URI does not match	Register the URI from WI exactly, as a Web platform, with no trailing differences.
Sign-ins start failing months later	The client secret expired. Create a new one and paste its Value into Client secret in the connection settings.
A person sees "Needs new access — connect again" under Settings	You changed the connection's permissions after they connected. They select Connect again to receive the new access.
Sending or saving drafts fails for people who connected earlier	The connection did not have Mail.Send or Mail.ReadWrite when they signed in. Add the permission in Entra and in WI, then ask them to connect again.
A function is greyed with "Needs the … permission"	Tick the permission in the connection's checklist (select Go to permissions), then Refresh functions.