<!-- source: https://modelux.ai/docs/guides/sso-okta -->

> Connect Okta as your SAML identity provider for Modelux.

# SSO with Okta

Step-by-step Okta setup. Assumes you have the **Super Admin** role in
your Okta tenant and **admin** or **owner** in Modelux.

If you haven't read the [SAML SSO overview](/docs/guides/sso), start
there.

## 1. Collect Modelux SP details

In a separate browser tab, open Modelux → **Settings → SSO**. You'll
copy these values into Okta in step 3:

- **SP Entity ID**
- **Assertion Consumer Service URL**
- **SP metadata XML** URL (optional — Okta doesn't accept metadata import
  for custom SAML apps; you'll paste the individual fields instead)

Keep the tab open; you'll also paste values **back** from Okta.

## 2. Create a SAML app in Okta

1. In the Okta admin console: **Applications → Applications → Create App
   Integration → SAML 2.0 → Next**.
2. **General Settings:**
   - App name: `Modelux`
   - (Optional) Upload the Modelux logo
   - Click **Next**.

## 3. Configure SAML settings

On the **Configure SAML** step:

- **Single sign-on URL:** paste Modelux's **Assertion Consumer Service
  URL**. Check *"Use this for Recipient URL and Destination URL"*.
- **Audience URI (SP Entity ID):** paste Modelux's **SP Entity ID**.
- **Name ID format:** `EmailAddress`
- **Application username:** `Email`

### Attribute Statements

Add these (case-sensitive):

| Name | Name format | Value |
| --- | --- | --- |
| `email` | Basic | `user.email` |
| `firstName` | Basic | `user.firstName` |
| `lastName` | Basic | `user.lastName` |
| `displayName` | Basic | `user.displayName` |

Click **Next**, pick *"I'm an Okta customer adding an internal app"*,
then **Finish**.

## 4. Copy Okta → Modelux

Back on your new Okta app's **Sign On** tab, click **View SAML setup
instructions**. Copy these into the Modelux **Identity provider** form:

| Okta field | Modelux field |
| --- | --- |
| *Identity Provider Issuer* | IdP Entity ID |
| *Identity Provider Single Sign-On URL* | IdP SSO URL |
| *X.509 Certificate* (download or copy the PEM block) | IdP certificate |

Set **Default role** to `member` (the typical choice).

Click **Test connection** in Modelux — this confirms the cert parses.
Then click **Save**.

## 5. Assign users in Okta

- On the Okta app's **Assignments** tab, click **Assign → Assign to
  People** (or Groups).
- Add yourself (and a test user if possible) to the app.

## 6. Verify domain + test

1. In Modelux **Settings → SSO**, add your email domain (e.g.
   `acme.com`). Publish the DNS TXT record we give you at
   `_modelux.acme.com` and click **Verify**.
2. In an incognito window, visit
   [app.modelux.ai/login](https://app.modelux.ai/login).
3. Click **Use SAML SSO**, enter your work email, and confirm you land
   back in the Modelux dashboard logged in.

## 7. Turn on enforcement

Once a non-admin test user has logged in successfully, return to
**Settings → SSO** and toggle **Require SAML for all members**. This
blocks password / Google logins for any member of your org.

> Don't enable enforcement until at least one org **owner** has
> successfully signed in via SAML. If the IdP config is wrong and
> enforcement is on, everyone is locked out.

## SCIM provisioning (optional)

To have Okta push user create / update / deactivate events into
Modelux, enable SCIM on the same app. See the
[SCIM provisioning guide](/docs/guides/scim#okta).

## Troubleshooting

- **"Invalid SAML assertion"** — the cert in Modelux doesn't match the
  Okta signing cert. Re-copy the x509 from Okta's setup instructions.
  Make sure you include `-----BEGIN CERTIFICATE-----` and
  `-----END CERTIFICATE-----`.
- **"No SSO configured for this email's domain"** — add the domain in
  Modelux and verify the TXT record.
- **Landing on /login instead of the dashboard after clicking the Okta
  tile** — IdP-initiated SSO works, but Okta needs the *Default
  RelayState* set. Modelux accepts either a missing or `/` RelayState;
  most Okta setups work out of the box.