> ## Documentation Index
> Fetch the complete documentation index at: https://openworklabs.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For agents: install the OpenWork desktop app with `brew install --cask openwork` (macOS) or from https://openworklabs.com/download. Do not run `npx openwork`; the npm package named `openwork` is a different project.
> Connect an agent to OpenWork with the MCP Gateway: `claude mcp add --transport http openwork https://api.openworklabs.com/mcp/agent`. Teams sign up at https://app.openworklabs.com?mode=sign-up.
> Step-by-step agent guide: https://openworklabs.com/docs/start-here/use-openwork-from-an-ai-agent.md
> Connect Slack (any organization admin): https://openworklabs.com/docs/slack/connect-slack.md. OpenWork in Slack (@openwork bot) is private alpha for approved organizations. Setup guide: https://openworklabs.com/docs/slack/overview.md. Agent skill: https://openworklabs.com/.well-known/agent-skills/set-up-openwork-slack/SKILL.md.

# Connect Microsoft 365

> Set up Outlook, calendars, OneDrive, SharePoint, and Teams for your OpenWork organization

An administrator sets up Microsoft 365 once in OpenWork Cloud. Each member
then signs in with their own work account, and their agent uses that account's
permissions.

## Before you start

You need an OpenWork role that can open and save the connector settings.
Organization owners and admins have it by default. A custom role needs **View
all connections**, **Manage connections** (to add the connector), **View OAuth
apps**, and **Manage OAuth apps**. You also need permission to manage an app
registration in your company's Microsoft Entra tenant. Organization-wide
consent also requires an authorized Entra administrator, such as a Cloud
Application Administrator or Application Administrator for the delegated
permissions used here. Azure subscription Owner access alone does not grant
that authority.

Use your existing company tenant and sign-in configuration. Connecting
Microsoft 365 does not require changing your domain federation or SSO setup.

## 1. Open the connection settings

In OpenWork Cloud, open **Manage › Connectors › Microsoft 365 › Settings**.
If Microsoft 365 is not listed, choose **Add connector** and select it.

Copy the **Redirect URI** shown by OpenWork. Hosted OpenWork uses:

```text theme={null}
https://api.openworklabs.com/v1/oauth-providers/microsoft-365/connect/callback
```

For a self-hosted deployment, use the address displayed by that deployment.

## 2. Find or register your Microsoft app

Open the [Microsoft Entra admin center](https://entra.microsoft.com), select
your company directory, and go to **Entra ID › App registrations › All
applications**. Select your existing OpenWork Microsoft 365 app.

For a new setup, choose **New registration**, name it **OpenWork Microsoft 365
Connector**, and select the single-tenant account type (**Single tenant only**
or **Accounts in this organizational directory only**, depending on the portal).
Register the app, then open **Authentication**, choose **Add Redirect URI**
(**Add a platform** in older portals), select **Web**, and add the exact
callback copied from OpenWork. If registration already offered a redirect URI
field, you can set the **Web** callback there instead.

![Microsoft Entra application registration form showing the application name, account types, and redirect URI](https://learn.microsoft.com/en-us/entra/identity-platform/media/howto-create-service-principal-portal/create-app.png)

Microsoft's example registration form. Use your own tenant and the callback shown by OpenWork.

On the app's **Overview** page, copy these values:

| Microsoft Entra field | OpenWork field |
| - | - |
| Directory (tenant) ID | Directory (tenant) ID |
| Application (client) ID | Client ID |

**Object ID** is a different identifier. Do not use it as the Client ID.
See Microsoft's [registration instructions](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal).

## 3. Create and save a client secret

In the same app registration:

1. Open **Certificates & secrets › Client secrets**.
2. Choose **New client secret**.
3. Add a description and select an expiry consistent with your company's policy.
4. Choose **Add** and immediately copy the complete **Value**.
5. Return to OpenWork's Microsoft 365 settings. Enter the tenant ID, client ID,
   and secret Value. For an existing connection, choose **Replace credentials**
   to reveal these fields.
6. Save the credentials using the button shown by OpenWork.

> [!WARNING]
>
> Copy the secret **Value**, not its **Secret ID**. Microsoft only shows the
> Value immediately after creation. If you leave without saving it, retrieve it
> from your approved secret manager or create another secret in the same app.

Keep the Value out of screenshots, chat, and support tickets. Record its expiry
so you can replace it before it expires. Microsoft's
[credential guide](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials)
explains the available credential options and secret lifetimes.

> [!NOTE]
>
> OpenWork's Microsoft 365 connector currently accepts a client secret, not a
> certificate or federated credential. Microsoft recommends certificate or
> federated credentials rather than secrets for production applications. If your
> organization prohibits client secrets, this setup does not meet that policy;
> consult your security administrator before proceeding.

## 4. Choose what your agent can do

Under **What your AI can do**, enable the capabilities your organization needs
and choose **Save permissions**.

| Service | Available choices |
| - | - |
| Outlook | Read mail, create drafts, manage mailbox items, or send mail |
| Calendar | Read events, or create and manage events |
| OneDrive | Read or update the member's own files, or every file they can open, including SharePoint libraries, files shared with them, and Teams files |
| SharePoint | Find sites and list their document libraries |
| Teams | Read chats, or send messages in existing chats |

Draft access requires mailbox read/write permission. It does not enable the
separate **Send Outlook email** option. Drafts, reply drafts, and calendar
events are plain text unless the agent asks for HTML, which keeps links, line
breaks, tables, and signatures. An HTML reply keeps the quoted original message
below it.

Calendar event creation can also book a Teams meeting: the agent asks for an
online meeting and the invitation carries a real join link, with no extra
Microsoft permission. If Microsoft returns no link, for example because Teams
meetings are turned off for Outlook in your tenant, the agent says so instead of
reporting a normal invitation.

With the **Outlook attachments** feature turned on for your organization, the
desktop app can also attach workspace files to a new draft or a reply draft:
up to ten files, each under 3 MB and 4 MiB in all. You approve each draft in
the chat, files are sent outside the model's context, and the draft is never
sent. If a file cannot be attached, the draft is moved to Deleted Items rather
than left without it. Agents can also read the files attached to an Outlook
message.

File permissions that mention “all
files” can include shared files the member can access beyond their own drive,
such as SharePoint libraries and files shared in Teams. Without them, file search
and pulls cover only the member's own OneDrive.

Microsoft's default consent policy does not let members approve the all-files
or SharePoint sites permissions themselves, so an administrator must grant
consent for the organization (step 5) before members can connect with them.

Review Microsoft's permission descriptions before consenting. They can cover
more than one OpenWork action.

### Microsoft Graph permissions

OpenWork requests **delegated permissions**, not **application permissions**.
The enabled choices determine the scopes requested during sign-in:

| OpenWork choice | Microsoft Graph delegated permission |
| - | - |
| Read Outlook mail | `Mail.Read` |
| Create and manage email drafts; manage read status, categories, and mailbox folders | `Mail.ReadWrite` |
| Send Outlook email | `Mail.Send` |
| Read Outlook calendar | `Calendars.Read` |
| Create and manage calendar events | `Calendars.ReadWrite` |
| Read OneDrive files | `Files.Read` |
| Create and update OneDrive files | `Files.ReadWrite` |
| Read all files the member can access | `Files.Read.All` |
| Full access to files the member can access | `Files.ReadWrite.All` |
| Find SharePoint sites and libraries | `Sites.Read.All` |
| Read Teams chats | `Chat.Read` |
| Send Teams chat messages | `Chat.Read` and `ChatMessage.Send` |

Sign-in also requests `openid`, `profile`, `email`, `offline_access`, and
`User.Read` to identify the member and renew their connection. If you configure
permissions manually in Entra, use **API permissions › Add a permission ›
Microsoft Graph › Delegated permissions**. Add only the permissions needed for
your enabled choices; do not substitute application permissions.

### Change permissions for an existing connection

Saving permissions does not add new Microsoft grants to existing member
connections. If a new choice needs access their account has not already
granted, grant any required admin consent and ask affected members to sign in
again. OpenWork shows **Sign in** (or **Reconnect**) for those accounts. An
existing broader grant can already cover the new choice, so not every change
requires sign-in.

## 5. Grant admin consent

An authorized Entra administrator chooses **Sign in** on the OpenWork
connection and reviews the permissions requested for the exact app. To approve
them for the organization, select **Consent on behalf of your organisation**
and **Accept**.

Members still sign in separately. OpenWork uses delegated access through each
member's account.

You can review the saved consent in **Entra ID › Enterprise apps › your app ›
Permissions**.

![Microsoft Entra enterprise application Permissions page with the Grant admin consent action](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/media/grant-tenant-wide-admin-consent/grant-tenant-wide-admin-consent.png)

Microsoft's example of the enterprise application Permissions page. Review your app's actual permissions before approving them.

If you grant consent through **App registrations › API permissions**, first
check that the declared permissions match OpenWork's enabled features.
Approving only the default `User.Read` permission does not cover mail,
calendar, file, or chat access. See Microsoft's
[admin consent guide](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent).

## 6. Connect and test a member account

Each person opens **My Library** in OpenWork Cloud and chooses **Sign in** on
Microsoft 365. On the connections page that opens, they choose **Sign in** again
on the highlighted Microsoft 365 row, select their company account, and
complete sign-in. In the desktop app, open **Library** from the main sidebar
(or **Settings › Library**), choose the **Connectors** filter, and select
**Sign in** for Microsoft 365.

If Microsoft 365 is missing from their Library, an OpenWork administrator
should check that the connector is set up and the member has access.

Confirm the account shows as connected, then try a read-only request for an
enabled service:

> Show my upcoming Outlook calendar events for tomorrow. Do not change anything.

A successful calendar read verifies calendar access. Other services can require
their own Microsoft 365 license, provisioning, and enabled permissions.

## Troubleshooting

| Problem | What to check |
| - | - |
| `AADSTS7000215`: invalid client secret | Save the complete secret **Value** from the same app registration. A Secret ID, masked value, or another app's secret will not work. |
| Secret Value is hidden | Microsoft cannot display it again. Retrieve the original from your secret manager or create another secret. |
| Wrong directory or account rejected | Match OpenWork's tenant ID and client ID to the app's Overview page. Use a work account in that tenant. |
| Need admin approval | An authorized Entra administrator must approve the requested permissions. If their role is eligible through PIM, activate it first. |
| Redirect URI mismatch | Register the exact callback displayed by OpenWork under the **Web** platform. |
| New permissions still ask for access | Save the enabled choices, grant any required admin consent, and have the affected member sign in again. Saving settings alone does not update their existing grant. |
| Connected, but a service call fails | Check enabled features, consent, and the member's mailbox, OneDrive, or Teams provisioning and license. |

## Replace an expiring secret

Create another secret in the same app and save its Value through **Replace
credentials** in OpenWork. Test a fresh connection before retiring the old
secret, and check whether another service still uses it.

Routine secret replacement keeps the same client ID and tenant ID. Replacing
only the secret does not itself disconnect existing member accounts.

> [!WARNING]
>
> Changing the client ID or tenant ID disconnects existing member accounts for
> that connector. This includes entering a different identifier for the same
> tenant, such as its domain name instead of its tenant ID. Treat switching apps
> or tenants as a migration: review the new app's permissions and consent, and
> plan for members to sign in again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.