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

# SAML SSO with Okta

> Set up SAML 2.0 single sign-on so users sign in to Sofie through Okta or another SAML identity provider.

SAML SSO lets users sign in to Sofie through your identity provider using SAML 2.0. This guide walks through a complete Okta setup, from creating the Okta app integration to verifying sign-in and disabling magic links.

Other SAML identity providers work the same way: give the provider Sofie's service provider values, then import the provider's metadata into Sofie.

<Note>
  Sofie supports two Okta sign-in methods: **SAML 2.0** (this guide) and **OpenID Connect**. They are configured in separate sections of **Organization Settings** > **General** and are independent of each other. If your identity team asked for SAML, use this guide. For the OIDC option, see [Okta SSO (OIDC)](/admin/okta-sso).
</Note>

## Before you start

You need:

* Okta administrator access with permission to create app integrations.
* A Sofie administrator account with access to **Organization Settings** > **General** and a passkey enrolled. Saving SSO settings requires a passkey confirmation.
* The Sofie domain your users sign in to.
* A test user assigned to the Okta app who can complete a sign-in.
* Magic-link sign-in left available until SAML sign-in is tested and verified.

## Sofie's service provider values

Sofie shows its service provider values in **Organization Settings** > **General** > **SAML 2.0 SSO**, under **1. Add these values to your identity provider**. Each value has a copy button, and they follow this pattern:

| Value                            | URL                                                  |
| -------------------------------- | ---------------------------------------------------- |
| **Single sign-on URL / ACS URL** | `https://<your-sofie-domain>/api/auth/saml/acs`      |
| **Audience URI / SP Entity ID**  | `https://<your-sofie-domain>/api/auth/saml/metadata` |
| **Single logout URL**            | `https://<your-sofie-domain>/api/auth/saml/slo`      |

The same section links to Sofie's **SP metadata** document and lets you download or copy Sofie's signing certificate. The metadata and certificate become available after you save SAML settings for the first time, because Sofie generates its signing key pair on first save.

Sofie expects the **email address NameID format**, signs its authentication requests, and supports encrypted assertions using the certificate published in its SP metadata.

<Note>
  If this section shows "Set NEXT\_PUBLIC\_URL or NEXTAUTH\_URL before configuring SAML" instead of URLs, the deployment's public URL is not configured yet. Contact whoever operates your Sofie deployment before continuing.
</Note>

## Step 1: Create the SAML app in Okta

<Steps>
  <Step title="Create a new app integration">
    In the Okta Admin Console, go to **Applications** > **Applications** and click **Create App Integration**. Choose **SAML 2.0** and click **Next**.
  </Step>

  <Step title="Name the app">
    Use a clear name such as `Sofie`, then click **Next** to reach **Configure SAML**.
  </Step>

  <Step title="Enter Sofie's service provider values">
    | Okta field                                         | Value                                                |
    | -------------------------------------------------- | ---------------------------------------------------- |
    | **Single sign-on URL**                             | `https://<your-sofie-domain>/api/auth/saml/acs`      |
    | **Use this for Recipient URL and Destination URL** | Leave checked.                                       |
    | **Audience URI (SP Entity ID)**                    | `https://<your-sofie-domain>/api/auth/saml/metadata` |
    | **Name ID format**                                 | **EmailAddress**                                     |
    | **Application username**                           | **Email**                                            |
  </Step>

  <Step title="Add attribute statements">
    Add these attribute statements so Sofie can show users' names:

    | Name        | Name format | Value            |
    | ----------- | ----------- | ---------------- |
    | `email`     | Unspecified | `user.email`     |
    | `firstName` | Unspecified | `user.firstName` |
    | `lastName`  | Unspecified | `user.lastName`  |

    The email NameID alone is enough to sign in, but without name attributes new users are created without a display name.
  </Step>

  <Step title="Finish the wizard">
    Complete the remaining feedback step and click **Finish**.
  </Step>

  <Step title="Assign users">
    On the app's **Assignments** tab, assign the people or groups who should be able to sign in to Sofie. Include your test administrator account.
  </Step>
</Steps>

Okta reference: [Create SAML app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm).

## Step 2: Copy the Okta metadata URL

<Steps>
  <Step title="Open the Sign On tab">
    In the Okta app integration, open the **Sign On** tab.
  </Step>

  <Step title="Copy the metadata URL">
    Under the SAML signing certificates or setup instructions area, copy the **Metadata URL**. It looks like `https://<your-okta-domain>/app/<app-id>/sso/saml/metadata`.
  </Step>
</Steps>

The metadata URL is the easiest option because it carries the Okta entity ID, sign-on URL, and signing certificate in one document. If your environment blocks Sofie from fetching the URL, download the metadata XML from the same tab instead and paste it into Sofie in the next step.

## Step 3: Import Okta metadata into Sofie

<Steps>
  <Step title="Open SAML settings in Sofie">
    In Sofie, go to **Organization Settings** > **General** and find **SAML 2.0 SSO**.
  </Step>

  <Step title="Import the metadata">
    Under **2. Import identity provider metadata**, paste the Okta metadata URL into **Metadata URL**, or paste the metadata document into **Or paste metadata XML**. Click **Import metadata**.
  </Step>

  <Step title="Review the imported values">
    Under **3. Review and save**, confirm the fields Sofie filled in from the metadata:

    | Field                        | What to check                                                                               |
    | ---------------------------- | ------------------------------------------------------------------------------------------- |
    | **Identity provider name**   | Sofie detects Okta automatically. Users will see **Sign in with Okta** on the login screen. |
    | **IdP entity ID**            | Must match the issuer Okta sends. Do not edit this unless Okta changes it.                  |
    | **SSO URL**                  | The Okta sign-on URL Sofie redirects users to.                                              |
    | **SLO URL (optional)**       | Filled in only if single logout is configured in Okta.                                      |
    | **IdP signing certificates** | The Okta signing certificate in PEM form. The field accepts more than one certificate.      |
  </Step>
</Steps>

## Step 4: Review attribute and access options

Expand **Attribute and access options** to review these settings. The defaults match the Okta configuration in this guide, so most deployments only need to decide on the toggles.

| Setting                                     | Default | What it does                                                                                                                  |
| ------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Email attribute**                         | `email` | The assertion attribute Sofie reads the email address from.                                                                   |
| **Display name attribute (optional)**       | Empty   | Set only if Okta sends a single full-name attribute.                                                                          |
| **First name attribute (optional)**         | Empty   | Sofie falls back to `firstName` and `givenName`.                                                                              |
| **Last name attribute (optional)**          | Empty   | Sofie falls back to `lastName`, `sn`, and `surname`.                                                                          |
| **Allowed email domains (optional)**        | Empty   | Comma-separated list of email domains allowed to sign in through SAML. Empty trusts any domain Okta asserts.                  |
| **Create users on first SAML sign-in**      | On      | Creates a Sofie account the first time an assigned Okta user signs in. When off, only existing Sofie users can sign in.       |
| **Allow IdP-initiated sign-in**             | Off     | Lets users launch Sofie from their Okta dashboard tile. When off, sign-in must start from the Sofie login page.               |
| **Always require fresh IdP authentication** | Off     | Sends ForceAuthn with each Sofie-initiated request. Most organizations should leave this off and rely on Okta session policy. |

If the attribute fields are left at their defaults, Sofie also reads standard SAML attributes (`mail`, `givenName`, `sn`, `displayName`) and falls back to the email NameID, so a conventional Okta app works without extra mapping.

## Step 5: Enable, save, and test

<Steps>
  <Step title="Enable SAML sign-in">
    Turn on **Enable SAML sign-in**.
  </Step>

  <Step title="Save SAML settings">
    Click **Save SAML settings** and complete the passkey confirmation. The section shows a **Not verified** badge until a sign-in succeeds.
  </Step>

  <Step title="Test SAML sign-in">
    Click **Test SAML sign-in**. Sofie redirects you to Okta; sign in with an account assigned to the Okta app. A successful sign-in returns you to organization settings and switches the badge to **Verified**.
  </Step>

  <Step title="Confirm the login page">
    Open the Sofie sign-in page in a private window and confirm the **Sign in with Okta** button appears and works for a regular test user.
  </Step>
</Steps>

<Note>
  Changing the IdP entity ID, SSO URL, certificates, or attribute settings resets the verification status. Complete another test sign-in after any change, especially if magic links are disabled.
</Note>

## How users sign in

* Users click **Sign in with Okta** on the Sofie login page, authenticate with Okta, and land in Sofie.
* If **Allow IdP-initiated sign-in** is on, users can also open Sofie from the Okta dashboard tile. When it is off, Sofie rejects sign-ins that do not start from the Sofie login page.
* Sofie sessions follow Sofie's standard session lifetime after sign-in. Turn on **Always require fresh IdP authentication** only if your policy requires re-authentication at Okta on every Sofie sign-in.

## User provisioning and account linking

With **Create users on first SAML sign-in** on, Sofie provisions accounts just in time:

* A new user is created on first sign-in with their email address already verified.
* If the user has a pending Sofie invitation, the invitation's role and group assignments apply.
* Otherwise the user gets the organization's default role.

Sofie links SAML sign-ins to existing accounts by email address, so users who previously signed in with magic links keep their history and access. An existing account must have a verified email address before it can be linked; a user who has never completed a magic-link sign-in should do that once, or be re-invited, before switching to SAML.

<Note>
  Group-to-role mapping from Okta is not available yet. Assign Sofie roles through invitations, the default role, or [user management](/admin/user-management).
</Note>

## Single logout

If Okta's single logout is configured, signing out of Sofie also ends the Okta session, and a logout initiated from Okta ends the user's Sofie sessions.

To enable it in Okta, edit the app integration's SAML settings, open **Show Advanced Settings**, enable single logout, set the logout URL to `https://<your-sofie-domain>/api/auth/saml/slo`, set the SP issuer to `https://<your-sofie-domain>/api/auth/saml/metadata`, and upload Sofie's signing certificate from the **Download signing certificate** button. Then re-import the Okta metadata in Sofie so the **SLO URL** field is filled in.

Single logout is optional. Without it, signing out of Sofie ends only the Sofie session.

## Disable magic links after rollout

Use **Disable magic links when SSO is enabled** in **Authentication Policy** to hide and block email magic-link sign-in once SAML is working.

This setting stays locked until an external sign-in method is verified — the settings page says "Verify Okta or SAML, or configure Microsoft SSO before enabling this setting" until then. Magic links also remain available whenever no verified provider exists, which prevents administrators from locking themselves out during setup.

<Warning>
  Complete a successful **Test SAML sign-in** with an administrator account before disabling magic links, and keep the Okta app assignment for administrators current. After magic links are disabled, SAML configuration mistakes can block sign-in until they are fixed.
</Warning>

## Certificate rotation

**When Okta rotates its signing certificate**, paste both the old and new certificates into **IdP signing certificates** before the rollover, then remove the old one after Okta completes it. Sofie accepts multiple certificates in that field for exactly this purpose. Re-importing the Okta metadata after the rollover also works.

**When Sofie's certificate needs rotation**, use **Rotate SP certificate** in the SAML section. Sofie's certificate is valid for five years, so this is rare. Rotating it invalidates the certificate Okta has on file — if Okta is configured for single logout or encrypted assertions, update the Okta app with the new certificate immediately, then run **Test SAML sign-in** again.

## Troubleshooting

<Accordion title="The Sign in with Okta button does not appear">
  Confirm **Enable SAML sign-in** is on and the IdP entity ID, SSO URL, and signing certificate are all saved. Sofie shows the button only when SAML is fully configured.
</Accordion>

<Accordion title="Sofie shows 'SAML is not ready'">
  SAML sign-in was attempted before configuration was complete. Finish the import and save steps, then use **Test SAML sign-in** from organization settings.
</Accordion>

<Accordion title="Sofie shows 'SAML sign-in was not accepted'">
  Sofie received a response from Okta but rejected it. Common causes:

  * The issuer in the response does not match the saved **IdP entity ID** — re-import the Okta metadata.
  * The user's email domain is not in **Allowed email domains**.
  * **Create users on first SAML sign-in** is off and the user has no Sofie account.
  * The user has an existing Sofie account whose email was never verified — have them sign in once with a magic link first.
  * The user launched Sofie from the Okta dashboard while **Allow IdP-initiated sign-in** is off.
  * The Okta signing certificate rotated and Sofie still has only the old one.
</Accordion>

<Accordion title="Okta shows an audience or ACS URL error">
  Confirm the **Audience URI (SP Entity ID)** and **Single sign-on URL** in the Okta app exactly match the values shown in Sofie, including the domain and `https://`.
</Accordion>

<Accordion title="Users sign in but names are missing or wrong">
  Confirm the Okta attribute statements use the names `email`, `firstName`, and `lastName`, or set the matching attribute names in **Attribute and access options**. Sofie sets the display name when it creates the account, so fix the mapping before rollout; existing users can update their name in account settings.
</Accordion>

<Accordion title="Users can sign in but have the wrong access">
  Okta authenticates the user; Sofie roles, groups, and Workspace membership still control access inside the app. Review the user's role and invitations in [user management](/admin/user-management).
</Accordion>

## Related docs

* [Okta SSO (OIDC)](/admin/okta-sso) for the OpenID Connect alternative to SAML.
* [Organization settings](/admin/organization-settings) for authentication policy and passkey requirements.
* [Microsoft SSO](/admin/microsoft-sso) for Microsoft Entra ID sign-in setup.
* [Users, groups, and roles](/admin/users-groups-roles) for the access model behind provisioning.
* [Security and passkeys](/account/security-and-passkeys) for user-level passkey setup.