Support
Connect Microsoft 365
For: Microsoft 365 admins
Register an app in your own Microsoft Entra tenant, give it the Microsoft Graph permissions below, and enter its Tenant ID, Client ID and a client secret in OneShift. You need an Entra role that can register apps and grant admin consent, and a OneShift role that can manage the workspace.
What the connector is for
The connector is what lets OneShift read your people’s Microsoft 365 activity and message them in Teams. Without it, the OneShift agent still logs time, but it cannot propose a day from your calendar, mail and Teams.
- Day review. The agent reads, for the day under review, calendar events, sent mail, Teams chat messages and channel posts, and proposes time entries from them.
- Bot notifications. The agent finds or installs itself for a member and opens a one-to-one chat so it can message them first.
- Outlook signature add-in. The Tenant ID you save here is how OneShift matches a Microsoft sign-in from Outlook to a workspace member. See Deploy the Outlook add-in.
Register the app in Microsoft Entra
Do this in the Microsoft Entra admin center. Microsoft’s screens can change, so follow the intent if a label differs.
- Sign in to the Microsoft Entra admin center for your organization’s tenant.
- Open App registrations and choose New registration.
- Give it a name you will recognize, for example “OneShift connector”. Choose single tenant: accounts in this organizational directory only.
- You do not need a redirect URI. The connector signs in as the app itself, with a client secret, and no one signs in through it.
- Register it, then copy the Directory (tenant) ID and Application (client) ID from its Overview page. You enter both in OneShift later.
Add the Graph permissions
Add every permission below as a Microsoft Graph application permission, not a delegated one. The list is the same as the one in the privacy policy and in the setup steps shown in the app.
- Open the app registration, then API permissions.
- Choose Add a permission, then Microsoft Graph, then Application permissions.
- Search for each permission in the table and add it.
| Permission | What OneShift uses it for | Needed for |
|---|---|---|
| User.Read.All | Finds a member’s Microsoft 365 account from their work email. | Day review and bot notifications |
| Calendars.Read | Reads the member’s calendar events for the day being reviewed. | Day review |
| Mail.Read | Reads the member’s sent mail for the day being reviewed. | Day review |
| Chat.Read.All | Reads the Teams chat messages the member wrote that day. | Day review (protected API) |
| Team.ReadBasic.All | Lists the teams the member belongs to. | Day review, channel posts |
| ChannelMessage.Read.All | Reads the channel posts the member wrote that day. | Day review, channel posts (protected API) |
| Channel.ReadBasic.All | Reads channel names so activity gets a readable title. | Day review, channel posts |
| AppCatalog.Read.All | Finds the OneShift agent in your organization’s app catalog. | Bot notifications |
| TeamsAppInstallation.ReadWriteForUser.All | Finds or installs the OneShift agent for a member and reads its chat. | Bot notifications |
| Chat.Create | Creates the one-to-one chat between the agent and a member when none exists. | Bot notifications |
The three notification permissions are for the agent’s messages. Leave them out only if you accept that the agent cannot message members first; see What stops working without a permission.
The same list is in the app’s own setup steps and in our privacy policy, which also says what is read and how long it is kept.
Grant consent and request Teams approval
Application permissions do nothing until an administrator consents to them. Two of them also need Microsoft’s approval.
Grant admin consent
- On the app’s API permissions page, choose the grant admin consent button for your tenant.
- Confirm. Every permission in the list should show as granted.
Whenever OneShift adds a permission to this list, the new one needs consent again. Check this page against the table above after an update.
Request Microsoft’s protected-API approval
Chat.Read.All and ChannelMessage.Read.All read Teams through Microsoft’s protected export APIs. Besides consent, Microsoft must approve your app’s Client ID for those APIs. Request access for the Client ID you copied earlier, using Microsoft’s process forprotected APIs in Microsoft Teams.
Reading Teams also needs a Teams license on the members whose messages are read; this is a Microsoft requirement for the protected APIs, noted in OneShift’s design record.
Connect it in OneShift
Now give OneShift the app’s details. You need a OneShift role that can manage the workspace; without it the Connectors tab is not shown.
Create a client secret
- In the app registration open Certificates & secrets and choose a new client secret.
- Pick a description and an expiry date. Note the date: see Rotate the client secret.
- Copy the secret Value now. Microsoft shows it only once.
Enter it in OneShift
- Open Workspace and the Connectors tab.
- Open the Microsoft card (“Entra ID app registration used to access Microsoft Graph APIs.”). Its settings include the same “Setup steps” as this article.
- Enter Tenant ID (the directory ID), Client ID (the application ID) and Client Secret.
- Select Test connection. “Connection successful.” means OneShift signed in and could list users. Otherwise you get “Could not connect to Microsoft Graph. Please check your settings.”
- Select Save. You see “Connector settings saved.”
Tenant ID and Client ID are required: leave one empty and the buttons stay disabled, or you get “Tenant ID and Client ID are required.” After saving, the secret shows only its first four characters followed by bullets.
Once it is saved, the Microsoft card on the Connectors tab shows as configured, and the agent starts proposing days from your members’ activity. Members do not link anything for their own account in this workspace.
Rotate the client secret
A client secret expires on the date you chose in Entra. After that the connector can no longer sign in, so replace the secret before it expires.
- In Entra, on the app’s Certificates & secrets, create a new client secret and copy its value. Keep the old one for now.
- In OneShift, open Workspace, Connectors, Microsoft.
- Replace the contents of Client Secret with the new value.
- Select Test connection, then Save. The new secret takes effect straight away.
- Delete the old secret in Entra.
The secret is stored encrypted. Put its expiry date in your calendar.
What stops working without a permission
Each permission is used by one kind of read or message. If one is missing, only that part fails; the rest keeps working.
| Permission | What stops working without it |
|---|---|
| User.Read.All | Nothing can be read for a member: OneShift cannot find their account. Test connection also fails. |
| Calendars.Read | Day review has no calendar events. |
| Mail.Read | Day review has no sent mail. |
| Chat.Read.All | Day review has no Teams chat messages. Also needs Microsoft’s protected-API approval. |
| Team.ReadBasic.All | Day review has no channel posts, because OneShift cannot list a member’s teams. |
| ChannelMessage.Read.All | Day review has no channel posts. Also needs Microsoft’s protected-API approval. |
| Channel.ReadBasic.All | Channel posts still appear, but their titles show the channel id instead of the channel name. |
| AppCatalog.Read.All | The agent cannot be found in your app catalog, so it cannot message members first. |
| TeamsAppInstallation.ReadWriteForUser.All | The agent cannot be installed for a member or find its chat, so it cannot message them first. |
| Chat.Create | The agent cannot create its one-to-one chat with a member who has none. |
If a member’s day review looks thin, a missing permission or a missing protected-API approval is the first thing to check.
Revoke access
You can stop OneShift reading Microsoft 365 at any time. The permission lives in your tenant, so you revoke it there.
- Stop all reads and messages: in Entra, delete the app registration, or remove its admin consent on the enterprise application.
- Stop only some: remove individual permissions from the app’s API permissions. The matching reads stop; see what stops working without a permission.
- Cut off access without touching the app: delete the client secret in Entra. The connector can then no longer sign in.
OneShift has no button that deletes the connector settings: the Tenant ID and Client ID stay saved, and you can reconnect later by creating a new secret and saving it. Activity read for day reviews is held in memory for up to five minutes and is not stored, as described in the privacy policy.