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

# Microsoft 365 integration

> Set up Sofie access to Microsoft email, calendar, OneDrive, and SharePoint through Microsoft Entra.

The Microsoft 365 integration lets Sofie work with Microsoft email, calendar, OneDrive, and SharePoint when your organization enables it and a user connects their account.

Use this guide if you administer Microsoft Entra apps for your organization or need to understand what your Microsoft admin must configure.

<Note>
  Your organization may use Sofie-managed OAuth configuration or your own Microsoft Entra app. Follow the option shown in **Organization Settings**.
</Note>

<Note>
  Microsoft Entra ID can also be used for Sofie sign-in. Use [Microsoft SSO](/admin/microsoft-sso) for sign-in setup. Configure Microsoft 365 data access under **Organization Settings** > **Integrations**.
</Note>

## What Sofie can use

Depending on permissions and user consent, Sofie may use Microsoft 365 to:

* Search and read email.
* Draft and send email after review.
* Read calendar events.
* Create or update calendar events after review.
* Search OneDrive and SharePoint files.
* Import useful files into a Workspace.
* Use file context in chat when available.

## Before you start

You need:

* Microsoft Entra administrator access.
* Permission to register or manage an app registration.
* The Sofie domain your users sign in to.
* Access to Sofie **Organization Settings** > **Integrations**.
* Agreement on which Microsoft capabilities users need.

## Redirect URI

Add this redirect URI to the Microsoft app registration, replacing the domain with your Sofie domain:

```text theme={null}
https://<your-sofie-domain>/api/integrations/callback/microsoft
```

Use the exact production domain users open in the browser. If your Sofie deployment has separate staging and production domains, add each environment separately.

If you already created a Microsoft app registration for [Microsoft SSO](/admin/microsoft-sso), you can add this integration redirect URI to that same app registration instead of creating a second app.

<Tip>
  Use one app registration when the same Microsoft tenant, IT owner, consent process, and secret rotation policy apply to both Sofie sign-in and Microsoft 365 data access. Use separate app registrations when your organization wants separate review, consent, audit ownership, or secret rotation.
</Tip>

## Register the Microsoft app

<Steps>
  <Step title="Open Microsoft Entra admin center">
    Go to **Microsoft Entra admin center** and open **App registrations**.
  </Step>

  <Step title="Create a new registration">
    Click **New registration**. Use a clear name such as `Sofie Microsoft 365 Integration`.
  </Step>

  <Step title="Choose supported account types">
    Choose the account type your organization allows. Most customer deployments use accounts in the organization tenant only.
  </Step>

  <Step title="Add a web redirect URI">
    Choose **Web** and add `https://<your-sofie-domain>/api/integrations/callback/microsoft`.
  </Step>

  <Step title="Save the application">
    Save the app registration.
  </Step>
</Steps>

Microsoft reference: [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/graph/auth-register-app-v2).

## Create credentials

<Steps>
  <Step title="Open Certificates & secrets">
    In the app registration, open **Certificates & secrets**.
  </Step>

  <Step title="Create a client secret">
    Create a new client secret with an expiration that matches your organization policy.
  </Step>

  <Step title="Copy the value once">
    Copy the secret value immediately. Microsoft does not show the full value later.
  </Step>

  <Step title="Store it in Sofie">
    Enter the client secret only in the secure Microsoft integration fields in Sofie.
  </Step>
</Steps>

Microsoft reference: [Add credentials to an application](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials).

<Warning>
  Do not paste client secrets into chat, CoDrafts, Workspaces, screenshots, or public docs. Use the secure integration settings fields only.
</Warning>

## Configure Microsoft Graph permissions

Sofie's Microsoft integration requests the following fixed set of scopes when a user connects their account:

| Type                      | Permission            | Use                                                                                |
| ------------------------- | --------------------- | ---------------------------------------------------------------------------------- |
| OpenID Connect            | `offline_access`      | Request a refresh token for continued access.                                      |
| Microsoft Graph delegated | `User.Read`           | Read the signed-in user's Microsoft profile.                                       |
| Microsoft Graph delegated | `Mail.Read`           | Read and search the signed-in user's email.                                        |
| Microsoft Graph delegated | `Mail.Send`           | Send email as the signed-in user.                                                  |
| Microsoft Graph delegated | `Calendars.Read`      | Read the signed-in user's calendars.                                               |
| Microsoft Graph delegated | `Calendars.ReadWrite` | Create, update, and delete events in the signed-in user's calendars.               |
| Microsoft Graph delegated | `Files.Read`          | Read the signed-in user's files.                                                   |
| Microsoft Graph delegated | `Files.ReadWrite`     | Create, update, and delete the signed-in user's files.                             |
| Microsoft Graph delegated | `Sites.Read.All`      | Read documents and list items in SharePoint sites on behalf of the signed-in user. |

Configure the Microsoft Graph permissions as **Delegated permissions**, not **Application permissions**. Delegated access does not give Sofie access beyond what the signed-in user can access.

Microsoft reference: [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference).

<Note>
  These scopes are fixed in the current Sofie integration flow. Sofie requests and checks for the complete set when a user connects Microsoft. Reducing the requested permissions requires a corresponding change to Sofie's integration configuration.
</Note>

## Use the SSO app registration

When your organization uses the same Microsoft app registration for SSO and Microsoft 365 integration:

* Configure the complete combined scope set in [Permissions for a shared app registration](/admin/microsoft-sso#permissions-for-a-shared-app-registration).
* In Sofie **Organization Settings** > **Integrations** > Microsoft, use the same client ID, tenant ID, and client secret value if Sofie asks for a custom OAuth app.
* Test sign-in first, then test a user Microsoft connection and review the consent prompt.

| Sofie feature             | Redirect URI                                                       |
| ------------------------- | ------------------------------------------------------------------ |
| Microsoft SSO             | `https://<your-sofie-domain>/api/auth/callback/microsoft-entra-id` |
| Microsoft 365 integration | `https://<your-sofie-domain>/api/integrations/callback/microsoft`  |

<Warning>
  Microsoft SSO and Microsoft 365 integration are still separate Sofie features. Enabling SSO lets users sign in with Microsoft. Enabling the Microsoft integration lets users connect Microsoft 365 sources such as email, calendar, OneDrive, and SharePoint.
</Warning>

For the full combined workflow, see [Set up SSO first, then integration](/admin/microsoft-sso#set-up-sso-first-then-integration).

## Add values in Sofie

In Sofie, go to **Organization Settings** > **Integrations** and open Microsoft.

Enter:

| Sofie field       | Microsoft value                                                                  |
| ----------------- | -------------------------------------------------------------------------------- |
| **Client ID**     | Application client ID from the app registration.                                 |
| **Client Secret** | Client secret value.                                                             |
| **Tenant ID**     | Directory tenant ID when your deployment requires tenant-specific configuration. |

Then enable Microsoft and save settings.

## Configure Microsoft sign-in policy

If your organization uses Microsoft Entra ID for Sofie sign-in, follow [Microsoft SSO](/admin/microsoft-sso).

After Microsoft sign-in is configured, review **Disable magic links when SSO is enabled** in **Authentication Policy**. Turning it on hides and blocks email magic-link sign-in while Microsoft SSO is enabled and fully configured. Magic links stay available if no SSO provider is enabled.

## Test the connection

<Steps>
  <Step title="Connect a test user">
    Use a user account with representative but limited Microsoft access.
  </Step>

  <Step title="Review consent">
    Confirm the consent screen lists the expected Microsoft permissions.
  </Step>

  <Step title="Test read actions">
    Ask Sofie to search email, calendar, OneDrive, or SharePoint content that the test user can access.
  </Step>

  <Step title="Test write actions carefully">
    If enabled, test email send or calendar creation with safe recipients and test events.
  </Step>

  <Step title="Import a file">
    Search OneDrive or SharePoint and import a test file into a Workspace if that workflow is enabled.
  </Step>
</Steps>

## User prompt examples

```text theme={null}
Search SharePoint for files about PPQ sampling rationale. Return file name, location, likely relevance, and whether it should be imported into the validation Workspace.
```

```text theme={null}
Find calendar meetings with the validation team next week and draft a proposed agenda. Do not create or update any event yet.
```

```text theme={null}
Search recent email for open questions about CAPA effectiveness. Summarize the questions and list sender, date, and thread title.
```

## Troubleshooting

<Accordion title="Users cannot connect Microsoft">
  Confirm Microsoft is enabled in Sofie, the redirect URI matches exactly, the app registration has a valid client secret, and user consent is allowed by your Microsoft tenant policy.
</Accordion>

<Accordion title="Sofie can read email but cannot send">
  Check whether the Microsoft app has send permissions, whether admin consent is required, and whether the user has permission to send from the mailbox.
</Accordion>

<Accordion title="SharePoint files do not appear">
  Confirm the user can open the site directly in Microsoft 365. Then check whether the integration includes the SharePoint-related permissions your organization allows.
</Accordion>

<Accordion title="The connection stopped working">
  Check whether the client secret expired, the app registration changed, or your organization changed conditional access or consent policies.
</Accordion>

## Official Microsoft references

* [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/graph/auth-register-app-v2)
* [Add a redirect URI to an app registration](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-redirect-uri)
* [Add credentials to an application](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials)
* [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference)