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

# Okta SSO (OIDC)

> Set up Okta OpenID Connect single sign-on for Sofie sign-in.

Okta SSO with OpenID Connect lets users sign in to Sofie with their Okta account through a customer-managed Okta OIDC web application.

<Note>
  Sofie supports two Okta sign-in methods: **OpenID Connect** (this guide) and **SAML 2.0**. If your identity team asked for SAML — the common choice for enterprise Okta deployments — use [SAML SSO with Okta](/admin/saml-sso) instead. Configure one method or the other, not both.
</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.
* Magic-link sign-in left available until Okta sign-in is tested.

## Sign-in redirect URI

Add this redirect URI to the Okta application, replacing the domain with your Sofie domain:

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

Sofie shows the exact deployment value, with a copy button, in **Organization Settings** > **General** > **Okta Authentication**. Use the exact URI — Okta does not accept wildcards here.

## Create the Okta application

<Steps>
  <Step title="Create a new app integration">
    In the Okta Admin Console, go to **Applications** > **Applications** and click **Create App Integration**. Choose **OIDC - OpenID Connect**, then **Web Application**.
  </Step>

  <Step title="Enable the Authorization Code grant">
    Under grant types, make sure **Authorization Code** is enabled.
  </Step>

  <Step title="Add the sign-in redirect URI">
    Add `https://<your-sofie-domain>/api/auth/callback/okta` as a sign-in redirect URI.
  </Step>

  <Step title="Assign users">
    Assign the users or groups allowed to access Sofie, including your test administrator account.
  </Step>

  <Step title="Copy the client credentials">
    From the application's **Client Credentials** section, copy the **Client ID** and the **Client secret**.
  </Step>
</Steps>

## Add values in Sofie

In Sofie, go to **Organization Settings** > **General**, find **Okta Authentication**, and turn on **Enable Okta** to show the configuration fields.

| Sofie field       | Okta value                                                           |
| ----------------- | -------------------------------------------------------------------- |
| **Client ID**     | The client ID from the application's Client Credentials section.     |
| **Issuer URL**    | Your Okta organization URL, such as `https://customer.okta.com`.     |
| **Client Secret** | The client secret from the application's Client Credentials section. |

Click **Save Changes** and complete the passkey confirmation.

<Note>
  For standard SSO, use the organization URL as the issuer. Use `/oauth2/default` or another custom authorization server only when the Okta administrator has configured its access policy for this application.
</Note>

<Warning>
  Do not paste client secrets into chat, CoDrafts, Workspaces, screenshots, or public docs. Use the secure organization settings fields only. If a secret is already saved, leave **Client Secret** blank unless you are rotating it.
</Warning>

## Test Okta sign-in

Click **Test Okta sign-in** in the **Okta Authentication** section and complete the Okta sign-in with an assigned account. A successful test marks the provider verified, which is required before magic links can be disabled.

Then open the Sofie sign-in page in a private window and confirm the **Sign in with Okta** button works for a regular test user. Sign-in requests the `openid`, `profile`, and `email` scopes.

## User provisioning and account linking

* A new user is created on first Okta sign-in. If the user has a pending Sofie invitation, its role and group assignments apply; otherwise the user gets the organization's default role.
* Sofie links Okta sign-ins to existing accounts by email address, so users who previously used magic links keep their history and access. Existing accounts must have a verified email address to be linked.
* Okta groups do not map to Sofie roles. Assign roles through invitations, the default role, or [user management](/admin/user-management).

## Disable magic links after rollout

Once Okta sign-in is verified, you can turn on **Disable magic links when SSO is enabled** in **Authentication Policy**. The setting stays locked until an external provider is verified, which prevents administrator lockout during setup. See [Organization settings](/admin/organization-settings) for the full policy behavior.

## Troubleshooting

<Accordion title="The Sign in with Okta button does not appear">
  Confirm **Enable Okta** is on and the client ID, issuer URL, and client secret are all saved.
</Accordion>

<Accordion title="Okta shows a redirect URI error">
  Confirm the application includes `https://<your-sofie-domain>/api/auth/callback/okta` exactly, with no wildcard port and the correct domain and protocol.
</Accordion>

<Accordion title="Sign-in fails after entering the issuer URL">
  Use the plain organization URL such as `https://customer.okta.com`. If you used `/oauth2/default` or a custom authorization server, confirm its access policy allows this application.
</Accordion>

<Accordion title="Okta sign-in stops working after setup">
  Check whether the client secret was rotated in Okta, the application was deactivated, or the user's assignment was removed.
</Accordion>

## Related docs

* [SAML SSO with Okta](/admin/saml-sso) for the SAML 2.0 alternative.
* [Organization settings](/admin/organization-settings) for authentication policy.
* [Microsoft SSO](/admin/microsoft-sso) for Microsoft Entra ID sign-in setup.