Skip to main content
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.
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).

​
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: 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.
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.

​
Step 1: Create the SAML app in Okta

1

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

Name the app

Use a clear name such as Sofie, then click Next to reach Configure SAML.
3

Enter Sofie's service provider values

4

Add attribute statements

Add these attribute statements so Sofie can show users’ names:The email NameID alone is enough to sign in, but without name attributes new users are created without a display name.
5

Finish the wizard

Complete the remaining feedback step and click Finish.
6

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.
Okta reference: Create SAML app integrations.

​
Step 2: Copy the Okta metadata URL

1

Open the Sign On tab

In the Okta app integration, open the Sign On tab.
2

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

1

Open SAML settings in Sofie

In Sofie, go to Organization Settings > General and find SAML 2.0 SSO.
2

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

Review the imported values

Under 3. Review and save, confirm the fields Sofie filled in from the metadata:

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

1

Enable SAML sign-in

Turn on Enable SAML sign-in.
2

Save SAML settings

Click Save SAML settings and complete the passkey confirmation. The section shows a Not verified badge until a sign-in succeeds.
3

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

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

​
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.
Group-to-role mapping from Okta is not available yet. Assign Sofie roles through invitations, the default role, or user management.

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

​
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

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.
SAML sign-in was attempted before configuration was complete. Finish the import and save steps, then use Test SAML sign-in from organization settings.
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.
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://.
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.
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.