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.

01

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.
One app per workspace, in your tenant. The app is single-tenant: you register it in your own Microsoft Entra tenant and nobody at OneShift can do it for you. It uses application permissions, so it reads for every member of the tenant with one credential. The exact list is in Add the Graph permissions.
Members in another organization’s tenant. This connector covers your own tenant. A member who also works inside a customer’s Microsoft 365 links that account themselves; see Linked Microsoft accounts.
02

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.

  1. Sign in to the Microsoft Entra admin center for your organization’s tenant.
  2. Open App registrations and choose New registration.
  3. Give it a name you will recognize, for example “OneShift connector”. Choose single tenant: accounts in this organizational directory only.
  4. 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.
  5. Register it, then copy the Directory (tenant) ID and Application (client) ID from its Overview page. You enter both in OneShift later.
03

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.

  1. Open the app registration, then API permissions.
  2. Choose Add a permission, then Microsoft Graph, then Application permissions.
  3. Search for each permission in the table and add it.
PermissionWhat OneShift uses it forNeeded for
User.Read.AllFinds a member’s Microsoft 365 account from their work email.Day review and bot notifications
Calendars.ReadReads the member’s calendar events for the day being reviewed.Day review
Mail.ReadReads the member’s sent mail for the day being reviewed.Day review
Chat.Read.AllReads the Teams chat messages the member wrote that day.Day review (protected API)
Team.ReadBasic.AllLists the teams the member belongs to.Day review, channel posts
ChannelMessage.Read.AllReads the channel posts the member wrote that day.Day review, channel posts (protected API)
Channel.ReadBasic.AllReads channel names so activity gets a readable title.Day review, channel posts
AppCatalog.Read.AllFinds the OneShift agent in your organization’s app catalog.Bot notifications
TeamsAppInstallation.ReadWriteForUser.AllFinds or installs the OneShift agent for a member and reads its chat.Bot notifications
Chat.CreateCreates 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.

05

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

  1. In the app registration open Certificates & secrets and choose a new client secret.
  2. Pick a description and an expiry date. Note the date: see Rotate the client secret.
  3. Copy the secret Value now. Microsoft shows it only once.
Customer tenants need a secret. The Client Secret field says “Leave empty to use managed identity”. That only works for OneShift’s own connector in OneShift’s home tenant, where the platform’s identity is trusted by the app. An app you register in your tenant has no such trust, so with an empty secret the connection fails. Always paste a secret.

Enter it in OneShift

  1. Open Workspace and the Connectors tab.
  2. Open the Microsoft card (“Entra ID app registration used to access Microsoft Graph APIs.”). Its settings include the same “Setup steps” as this article.
  3. Enter Tenant ID (the directory ID), Client ID (the application ID) and Client Secret.
  4. 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.”
  5. 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.

Test connection checks sign-in and User.Read.All only. It lists one user. A missing calendar, mail, Teams or notification permission, or a missing protected-API approval, still passes the test and then fails when the agent runs. Check the permissions against the table.

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.

06

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.

  1. In Entra, on the app’s Certificates & secrets, create a new client secret and copy its value. Keep the old one for now.
  2. In OneShift, open Workspace, Connectors, Microsoft.
  3. Replace the contents of Client Secret with the new value.
  4. Select Test connection, then Save. The new secret takes effect straight away.
  5. Delete the old secret in Entra.
Leave the field alone to keep the secret. If you change only the Tenant ID or Client ID, the stored secret is kept. If you clear the Client Secret field and save, the secret is removed and the connector stops working for a customer tenant.

The secret is stored encrypted. Put its expiry date in your calendar.

07

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.

PermissionWhat stops working without it
User.Read.AllNothing can be read for a member: OneShift cannot find their account. Test connection also fails.
Calendars.ReadDay review has no calendar events.
Mail.ReadDay review has no sent mail.
Chat.Read.AllDay review has no Teams chat messages. Also needs Microsoft’s protected-API approval.
Team.ReadBasic.AllDay review has no channel posts, because OneShift cannot list a member’s teams.
ChannelMessage.Read.AllDay review has no channel posts. Also needs Microsoft’s protected-API approval.
Channel.ReadBasic.AllChannel posts still appear, but their titles show the channel id instead of the channel name.
AppCatalog.Read.AllThe agent cannot be found in your app catalog, so it cannot message members first.
TeamsAppInstallation.ReadWriteForUser.AllThe agent cannot be installed for a member or find its chat, so it cannot message them first.
Chat.CreateThe 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.

Outlook signature add-in. It does not use any of these permissions. It needs the Tenant ID saved on this card to match the Microsoft tenant of the person who signs in from Outlook. OneShift does not check the Tenant ID against the credentials when you save it, so enter it carefully.
08

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.