Microsoft 365 Integration
The Microsoft 365 integration connects your Azure AD tenant to concorbit so individual users can sync their Outlook calendar and contacts, log email activity on contacts, show their Teams presence dot, and link OneDrive files into the app without uploading copies.
URL: /settings/integrations/microsoft
Required permission: settings.tenant
How to get there
Go to Settings from the sidebar.
Open the Microsoft 365 card (under Integrations).
Two phases of setup
Setting up M365 is two-sided: your workspace admin registers a single Azure AD application for the whole tenant, and each individual user authorises their personal Microsoft account against that app.
The app registration happens once (Steps 1–5 below).
Each user then clicks Connect your Microsoft account under their own login to authorise and start syncing.
Phase 1: Admin setup (before connection)
The page walks you through five steps:
Step 1: Create an App Registration
Click Open Azure Portal to jump to the App registrations page, then click New registration.
Step 2: Configure the app
Fill the Azure form:
| Field | Value |
|---|---|
| Name | Concorbit |
| Supported account types | Accounts in this organizational directory only |
| Redirect URI (Web) | Copy from the concorbit page by clicking the copy button next to the URI. It ends in /integrations/microsoft/callback. |
Step 3: Enter credentials
From your new Azure app's Overview page, copy:
| concorbit field | Azure source |
|---|---|
| Application (client) ID | Overview → Application (client) ID |
| Directory (tenant) ID | Overview → Directory (tenant) ID |
| Client secret | Certificates & secrets → New client secret → copy the Value (not the ID). |
Paste into concorbit and click Save credentials. The client secret is encrypted at rest.
Step 4: API permissions checklist
In Azure, go to API permissions → Add a permission → Microsoft Graph → Delegated permissions and add each of:
| Permission | Enables |
|---|---|
| Calendars.ReadWrite | Two-way calendar sync |
| Contacts.ReadWrite | Two-way contact sync |
| Mail.Read | Read email subjects to log activity on contacts |
| Presence.Read | Show Teams availability on user avatars |
| User.Read | Basic sign-in profile (usually pre-added by Azure) |
| Files.Read | Browse OneDrive files for document linking |
Click Grant admin consent after adding them. Without admin consent, individual users will be prompted to consent each time they sign in.
Step 5: Save & Connect
Back on the concorbit page, click Connect Microsoft 365. This starts the OAuth flow: you'll be redirected to Microsoft, sign in, approve the permissions, and redirected back.
Phase 2: After connection
Once connected, the page becomes a status dashboard.
Connection status
Connected on: the date the admin first connected.
Token status: "Valid (expires in X days)" or "Expired, reconnect". User refresh tokens are long-lived but not forever; reconnect if yours expires.
Last sync: the last time a scheduled sync ran successfully.
Sync status:
healthy,error, ortoken_expired. Errors surface the message below.
Permissions
Tick/cross next to each of the six required permissions. If a permission is missing (e.g. admin forgot to add it), the feature that needs it is disabled below.
Feature toggles
Each toggle is gated on the relevant permission being granted. Flipping a toggle on schedules a background sync job; flipping it off stops it. Changes save immediately.
| Toggle | Requires | Effect |
|---|---|---|
| Sync calendar with Outlook | Calendars.ReadWrite | Two-way sync of Outlook calendar ↔ concorbit appointments, every 5 minutes. |
| Sync contacts with Outlook | Contacts.ReadWrite | Two-way sync of Outlook contacts ↔ concorbit contacts, every 5 minutes. |
| Log email activity on contacts | Mail.Read | Reads email subjects and timestamps and logs them as activities on matching contacts, every 15 minutes. Email body content is not read or stored. |
| Show Teams presence | Presence.Read | Puts a coloured dot on user avatars matching their current Teams status. Polls every 2 minutes. |
| OneDrive file linking | Files.Read | Lets users browse OneDrive and attach files to records as links (no copy is uploaded). |
Actions
Test Connection: runs a quick authenticated call to Microsoft Graph to confirm credentials still work. Shows your name and email on success.
Reconnect: shown when the token is expired. Re-runs the OAuth flow.
Disconnect: removes the tenant-wide app registration and all user tokens. Any scheduled sync tasks are deactivated. Users will need to reconnect individually afterwards.
Single Sign-On (SSO)
Once your workspace is connected, you can let staff sign in to concorbit by clicking Sign in with Microsoft on the login page instead of typing a password. Use the Single Sign-On card on this page to control it.
Master switch
Allow staff to sign in with Microsoft: when on, the unified login page shows a "Sign in with Microsoft" button for your workspace. When off, the button is hidden and SSO requests are rejected.
Branded redirect (host-aware OAuth round-trip)
By default, the OAuth round-trip with Microsoft uses concorbit.com as the callback host, so even if your users started on app.your-company.com, they briefly bounce to concorbit.com mid sign-in. Flipping Use this workspace's host for the Microsoft round-trip on keeps the entire flow on your branded host (your custom domain or your <slug>.concorbit.com subdomain), so the Microsoft consent screen shows your URL and the redirect-back lands on your domain.
Before flipping this on, register the host-specific callback URI in your Azure AD app:
Open your Azure portal → App registrations → the concorbit app you set up earlier → Authentication.
Under Web platform redirect URIs, click Add URI.
Paste the URI concorbit shows you (Settings > Microsoft 365 > Single Sign-On > Azure AD redirect URIs). Register whichever URI matches the host you'll actually sign in on: the subdomain URI if you use
<slug>.concorbit.com, the custom_domain URI if you have one. The platform URI is optional unless you also expect users to sign in viaconcorbit.comdirectly.Save the Azure changes.
Flip the Use this workspace's host… toggle on.
If you flip it on without registering the URI first, Microsoft will reject the sign-in with redirect_uri_mismatch. Flipping it back off restores the original behaviour immediately.
The full security model behind this (host validation, cross-host replay defence, fail-closed on mid-flight domain disable) is documented in docs/internal-guide/m365-sso-custom-domain-plan-2026-04.md for engineers who want the detail.
Notes and gotchas
Each user authorises independently. Admin setup only handles the workspace app registration. Every user who wants calendar/contact sync must click Connect your Microsoft account after the admin is done.
Check "Grant admin consent" in Azure. Without it, users get the consent prompt mid-flow and some permissions (like Presence.Read) often don't work correctly.
Mail.Read does not read body content. Only subjects and timestamps are logged as activities. If your compliance policy is strict about email contents, verify this matches your requirements; the permission name is misleading.
Calendar and contact sync is two-way. Creating an appointment in Outlook creates one in concorbit; creating one in concorbit creates one in Outlook. Conflict resolution uses last-modified-wins.
OneDrive linking does not copy files. concorbit stores only the OneDrive item ID + webUrl; the file lives in your user's OneDrive. If the user leaves the company and their OneDrive is deactivated, the linked files become inaccessible.
The client secret has an expiry (defaults to 6–24 months in Azure). Set a calendar reminder to generate a new secret before it expires, otherwise the integration silently breaks.