> ## 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 SSO

> Set up Microsoft Entra ID single sign-on for Sofie sign-in.

Microsoft SSO lets users sign in to Sofie with their Microsoft work account through Microsoft Entra ID.

Use this guide if you administer Microsoft Entra app registrations or need to coordinate Sofie sign-in setup with your identity team.

<Note>
  Microsoft SSO controls Sofie sign-in. Microsoft 365 data access is configured separately under **Organization Settings** > **Integrations**. For email, calendar, OneDrive, and SharePoint access, see [Microsoft 365 integration](/admin/integrations/microsoft-365).
</Note>

## 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** > **General**.
* A test administrator account that can sign in with Microsoft.
* A recovery plan before disabling magic-link sign-in.

## 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/auth/callback/microsoft-entra-id
```

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 plan to use the same app registration for Microsoft 365 data access, add the integration redirect URI to the same app registration too:

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

## 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 SSO`.
  </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/auth/callback/microsoft-entra-id`.
  </Step>

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

  <Step title="Copy app identifiers">
    Copy the **Application (client) ID** and **Directory (tenant) ID**. You will enter both values in Sofie.
  </Step>
</Steps>

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

## Create a client secret

<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 secret value">
    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 Entra ID Authentication 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 organization settings fields only.
</Warning>

## Review permissions and consent

Sofie uses Microsoft Entra ID through OAuth and OpenID Connect. The sign-in flow requests the following fixed set of scopes:

| Type                      | Permission            | Use                                                                  |
| ------------------------- | --------------------- | -------------------------------------------------------------------- |
| OpenID Connect            | `openid`              | Sign users in with OpenID Connect.                                   |
| OpenID Connect            | `profile`             | Read the signed-in user's basic profile claims.                      |
| OpenID Connect            | `email`               | Read the signed-in user's email claim when available.                |
| 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 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. |

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.

<Note>
  These scopes are fixed in the current Sofie sign-in flow. Sofie requests the mail and calendar permissions even when you configure Microsoft SSO separately from the Microsoft 365 integration.
</Note>

<Tip>
  Review the Microsoft consent screen with your identity team before broad rollout. Users should understand whether they are consenting to sign-in only or to additional Microsoft 365 capabilities.
</Tip>

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

## Use one app for SSO and Microsoft 365

You can use one Microsoft Entra app registration for both Sofie sign-in and Microsoft 365 data access.

This is often the simplest setup when the same Microsoft tenant, IT owner, consent process, and secret rotation policy apply to both features. Use separate app registrations when your identity team wants sign-in and Microsoft 365 data access reviewed, consented, audited, or rotated independently.

When you use one app registration, configure both redirect URIs on the same Microsoft app:

| 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`  |

Then use the same Microsoft values in both Sofie settings areas:

| Sofie area                                                                      | Values to enter                                                                                |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Organization Settings** > **General** > **Microsoft Entra ID Authentication** | Application client ID, directory tenant ID, and client secret value.                           |
| **Organization Settings** > **Integrations** > Microsoft                        | The same client ID, tenant ID, and client secret value when Sofie asks for a custom OAuth app. |

<Note>
  Enabling Microsoft SSO does not automatically enable Microsoft 365 data access for users. SSO controls sign-in. The Microsoft integration controls access to email, calendar, OneDrive, and SharePoint.
</Note>

<Warning>
  A shared app registration can show users or admins a broader Microsoft consent prompt because the app may request both sign-in scopes and Microsoft 365 delegated permissions. Review the consent screen before rollout.
</Warning>

### Permissions for a shared app registration

If one app registration supports both Microsoft SSO and the Microsoft 365 integration, configure the complete combined set below:

| Type                      | Permission            |
| ------------------------- | --------------------- |
| OpenID Connect            | `openid`              |
| OpenID Connect            | `profile`             |
| OpenID Connect            | `email`               |
| OpenID Connect            | `offline_access`      |
| Microsoft Graph delegated | `User.Read`           |
| Microsoft Graph delegated | `Mail.Read`           |
| Microsoft Graph delegated | `Mail.Send`           |
| Microsoft Graph delegated | `Calendars.Read`      |
| Microsoft Graph delegated | `Calendars.ReadWrite` |
| Microsoft Graph delegated | `Files.Read`          |
| Microsoft Graph delegated | `Files.ReadWrite`     |
| Microsoft Graph delegated | `Sites.Read.All`      |

This combined set includes every scope requested by either flow. Users still connect the Microsoft 365 integration separately after signing in with Microsoft.

## Set up SSO first, then integration

Use this sequence when your organization wants one Microsoft app registration for both features.

<Steps>
  <Step title="Create the Microsoft app registration">
    Register the app in Microsoft Entra ID and add the SSO redirect URI: `https://<your-sofie-domain>/api/auth/callback/microsoft-entra-id`.
  </Step>

  <Step title="Create and copy the client secret">
    Create a client secret in **Certificates & secrets** and copy the secret **Value**.
  </Step>

  <Step title="Enable Microsoft SSO in Sofie">
    In Sofie, open **Organization Settings** > **General** > **Microsoft Entra ID Authentication**. Enter the client ID, tenant ID, and client secret value, turn on **Enable Microsoft Entra ID**, and click **Save Changes**.
  </Step>

  <Step title="Test Microsoft sign-in">
    Use a fresh browser session and confirm a test administrator can click **Sign in with Microsoft** and reach Sofie.
  </Step>

  <Step title="Add the integration redirect URI">
    In the same Microsoft app registration, add `https://<your-sofie-domain>/api/integrations/callback/microsoft`.
  </Step>

  <Step title="Review Microsoft Graph permissions">
    Add or approve the complete delegated permission set in [Permissions for a shared app registration](#permissions-for-a-shared-app-registration).
  </Step>

  <Step title="Enable Microsoft integration in Sofie">
    In Sofie, open **Organization Settings** > **Integrations** and open Microsoft. If Sofie asks for a custom OAuth app, enter the same client ID, tenant ID, and client secret value from the shared app registration. Then enable Microsoft and save settings.
  </Step>

  <Step title="Test a user connection">
    Ask a test user to connect Microsoft from Sofie and review the Microsoft consent prompt before testing email, calendar, OneDrive, or SharePoint workflows.
  </Step>
</Steps>

## Add values in Sofie

In Sofie, go to **Organization Settings** > **General** and find **Microsoft Entra ID Authentication**.

Enter:

| Sofie field                   | Microsoft value                                          |
| ----------------------------- | -------------------------------------------------------- |
| **Enable Microsoft Entra ID** | Turn this on when the app registration values are ready. |
| **Application (Client) ID**   | Application client ID from the app registration.         |
| **Directory (Tenant) ID**     | Directory tenant ID from the app registration.           |
| **Client Secret**             | Client secret value from **Certificates & secrets**.     |

Click **Save Changes**.

Sofie treats Microsoft SSO as fully configured only when Microsoft Entra ID is enabled and the client ID, tenant ID, and client secret are all saved.

<Note>
  If a client secret is already saved, leave **Client Secret** blank to keep the current secret. Enter a new secret value only when you want to rotate it.
</Note>

## Test Microsoft sign-in

<Steps>
  <Step title="Keep magic links available">
    Leave **Disable magic links when SSO is enabled** off until Microsoft sign-in has been tested.
  </Step>

  <Step title="Open a fresh browser session">
    Use a private window or a browser profile that is not already signed in to Sofie.
  </Step>

  <Step title="Start Microsoft sign-in">
    Open the Sofie sign-in page and click **Sign in with Microsoft**.
  </Step>

  <Step title="Complete Microsoft authentication">
    Sign in with a representative Microsoft account and complete any Microsoft consent or conditional access prompts.
  </Step>

  <Step title="Confirm Sofie access">
    Confirm the user lands in Sofie and has the expected role, group, and Workspace access.
  </Step>
</Steps>

Sofie can assign a role from an active invitation when a new OAuth user signs in. If no invitation role applies, Sofie uses the default role configured for the organization.

## Disable magic links after rollout

Use **Disable magic links when SSO is enabled** to hide and block email magic-link sign-in after Microsoft SSO is working.

When this setting is on:

* Users sign in with Microsoft, passkey, or another available method.
* Email magic links are unavailable only when Microsoft SSO is fully configured.
* Magic links stay available if Microsoft SSO is incomplete, which helps prevent administrator lockout during setup.

<Warning>
  Test Microsoft sign-in with an administrator account before disabling magic links. Authentication policy changes can block users until they complete the required sign-in flow.
</Warning>

## Rotate the client secret

<Steps>
  <Step title="Create a new secret in Microsoft Entra">
    In the app registration, create a new client secret and copy the secret **Value**.
  </Step>

  <Step title="Update Sofie">
    In **Organization Settings** > **General** > **Microsoft Entra ID Authentication**, paste the new value into **Client Secret**.
  </Step>

  <Step title="Save and test sign-in">
    Click **Save Changes**, then test **Sign in with Microsoft** before the old secret expires.
  </Step>

  <Step title="Remove the old secret">
    After testing succeeds, remove the old secret from Microsoft Entra if your organization policy requires it.
  </Step>
</Steps>

## Troubleshooting

<Accordion title="The Microsoft button does not appear on the sign-in page">
  Confirm **Enable Microsoft Entra ID** is on and the client ID, tenant ID, and client secret are all saved in **Organization Settings** > **General**.
</Accordion>

<Accordion title="Microsoft shows a redirect URI error">
  Confirm the app registration includes `https://<your-sofie-domain>/api/auth/callback/microsoft-entra-id` exactly. Check the domain, protocol, path, and environment.
</Accordion>

<Accordion title="Users can sign in but have the wrong access">
  Review the user's role, group, invitations, and Workspace membership in Sofie. Microsoft SSO authenticates the user, but Sofie roles and Workspaces still control access inside the app.
</Accordion>

<Accordion title="Microsoft sign-in stops working after setup">
  Check whether the client secret expired, the app registration changed, or your organization changed Microsoft conditional access, consent, or tenant policy.
</Accordion>

## Related docs

* [Organization settings](/admin/organization-settings) for authentication policy and organization settings.
* [Security and passkeys](/account/security-and-passkeys) for user-level passkey setup.
* [Microsoft 365 integration](/admin/integrations/microsoft-365) for Microsoft email, calendar, OneDrive, and SharePoint access.