> ## Documentation Index
> Fetch the complete documentation index at: https://docs.isotopes.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Okta SAML SSO setup

> Configure SAML 2.0 single sign-on between Okta and aidnn — domain verification, SAML app creation, wiring, and group-to-role mapping.

aidnn supports any identity provider that speaks SAML 2.0. This guide is the Okta-flavored worked example; the same pattern works for Microsoft Entra ID, AD FS, OneLogin, Auth0, JumpCloud, and most enterprise IdPs. For how SSO works in aidnn (domain routing, claim and role mapping), see the [Enterprise SSO overview](/administration/sso-overview).

This guide assumes:

* You have Okta admin access on the tenant where you want to enable aidnn SSO.
* You have aidnn admin access on the account you're configuring (the **Enterprise SSO** page in the admin panel sidebar is admin-only).
* DNS access to the email domain you'll be claiming, so you can add a verification TXT record.

The full setup takes about 30 minutes if you have all three on hand.

***

## Step 1 — Claim and verify your email domain in aidnn

aidnn's SAML resolver routes sign-in attempts based on the email's domain. Before you wire Okta up, you have to claim the domain in aidnn:

1. Sign in to aidnn as an admin.
2. Open **Admin panel → Enterprise SSO → Single sign-on tab → Domains**.
3. Click **Add domain** and enter the email domain your employees use (`acme.com`, not `mail.acme.com`).
4. aidnn returns a TXT record (`aidnn-verify=<token>`). Add it as a TXT record on the apex of `acme.com`.
5. Wait \~5 minutes for DNS propagation, then click **Recheck DNS** on the domain's row in the aidnn UI.

Public mail providers (`gmail.com`, `outlook.com`, etc.) are rejected — the resolver only routes based on domains you control. If verification fails, the UI surfaces the exact DNS lookup result so you can compare it to your provider's record.

You can claim multiple domains for one account (subsidiaries, acquired companies). Each one needs its own TXT record and verification.

***

## Step 2 — Create the SAML app in Okta

In your Okta admin console:

1. Go to **Applications → Applications → Create App Integration**.
2. Choose **SAML 2.0**, then click **Next**.
3. **App name**: `Isotopes AI` (or whatever your internal convention is). Optional app logo: upload the Isotopes AI brand mark from your marketing asset library.
4. Click **Next** to the SAML configuration screen and use the following values:

| Setting | Value |
| - | - |
| Single sign-on URL | `https://<your-aidnn-host>/api/auth/saml/acs/<account-slug>` |
| Audience URI (SP Entity ID) | Copy the **SP entity ID** value verbatim (see note below) |
| Name ID format | `EmailAddress` |
| Application username | `Email` |
| Response signature | Sign Response (default) |
| Assertion signature | Sign Assertion (default) |
| Signature algorithm | `RSA-SHA256` |
| Digest algorithm | `SHA256` |

For the **Single sign-on URL**, your `<account-slug>` is the per-account string embedded in the **ACS URL** shown in aidnn's admin panel SSO settings under **Service provider details** — copy that ACS URL verbatim rather than hand-assembling it.

For the **Audience URI (SP Entity ID)**, copy the **SP entity ID** value verbatim from that same **Service provider details** card. This value is deployment-wide — it is identical for every account on this aidnn deployment and does **not** contain your account slug. Do not set it to `https://<your-aidnn-host>/<account-slug>`; an Audience that doesn't match the SP entity ID exactly causes an `audience mismatch` rejection at sign-in.

5. Scroll to **Attribute Statements** and add at least:

| Name | Name format | Value |
| - | - | - |
| `email` | Unspecified | `user.email` |
| `name` | Unspecified | `user.displayName` |
| `groups` (optional) | Unspecified | `Matches regex: .*` |

The `email` claim is required — aidnn uses it as the user's unique identifier. The `name` claim is optional (admin display only). The `groups` claim is required only if you plan to map Okta groups to aidnn roles via the group-claim mapping (see Step 5 below).

6. Finish the wizard. On the resulting app page, open the **Sign On** tab and click **View SAML setup instructions** — copy:
   * The **Identity Provider Single Sign-On URL**
   * The **Identity Provider Issuer**
   * The **X.509 Certificate** (PEM-encoded)

You'll paste those into aidnn in the next step.

***

## Step 3 — Wire Okta into aidnn

Back in aidnn:

1. Open **Admin panel → Enterprise SSO → Single sign-on tab** and go to the **Identity provider** card.
2. Paste the three values from Okta:
   * **Identity Provider Issuer** → aidnn's **IdP entity ID** field
   * **Identity Provider Single Sign-On URL** → aidnn's **IdP SSO URL** field
   * **X.509 Certificate** → aidnn's **IdP signing certificate (PEM)** field
3. Click **Save and enable SAML** in the action bar at the bottom of the page. The form runs a structural validation of the certificate; a misformatted PEM is rejected with a specific error.

There is no separate "enable" step — saving the config for the first time generates the per-account SP keypair and turns SAML sign-in on. (We still recommend round-tripping a test sign-in immediately, per Step 4, before relying on it.) SAML is always optional: users whose email is in a verified domain are routed to SAML, and everyone else keeps their stored non-SAML sign-in method.

***

## Step 4 — Assign a test user in Okta and round-trip

1. In Okta, open the SAML app you created and go to **Assignments**.
2. Click **Assign → Assign to People** and add one test user (typically yourself).
3. In aidnn, open a fresh incognito window. Navigate to your aidnn host. Enter the test user's email. The resolver routes you to Okta. Authenticate via Okta. You should land back in aidnn signed in.

If the round-trip fails, aidnn surfaces the specific rejection reason (e.g. "signature invalid", "audience mismatch") — copy that into a support ticket if you can't resolve it from the SAML setup. The most common cause is a copy-paste mistake in the X.509 certificate or in the Audience URI.

If you ever need to turn SAML back off, use the **Disable SSO** button in the action bar (covered in the Troubleshooting section). Re-saving the config later re-enables it.

***

## Step 5 — (Optional) Map Okta groups to aidnn roles

aidnn assigns each user a role from their SAML assertion. The **Role mapping** card on the Enterprise SSO page's **Single sign-on tab** has two sections; configure either, both, or neither. A role pinned in the Members panel via **Take over role assignment**, or set by SCIM group provisioning, takes precedence over the assertion — see [role precedence](/administration/sso-overview#role-mapping).

* **Role from a SAML attribute.** Pick this when your Okta app emits a single string claim per user (e.g. `aidnn_role=admin`). Use Okta's expression-based claim values: under the SAML app's **Sign On** tab → **Attributes** → add a claim named `aidnn_role` with a value expression like `isMemberOfAnyGroup("00g…aidnn_admins") ? "admin" : "viewer"`. Then in aidnn, set the attribute name to `aidnn_role` and map each value to a role.
* **Role from a SAML group claim.** Pick this when you want aidnn to consume Okta's multi-value `groups` claim directly (the one you configured in Step 2 with the group filter). Set the group attribute name in aidnn to `groups`, then add priority-ordered rows mapping each Okta group **display name** to a role (e.g. `aidnn-admins → ADMIN`). **Okta emits group display names**, not GUIDs — so the rows read cleanly.

Rows are evaluated in order — first match wins. The default role applies when nothing matches either path.

***

## Troubleshooting

**"This account uses SAML SSO" banner appears for a user who shouldn't see it.** The user's email domain is verified for SSO. Remove the domain claim if that domain should not route through your IdP.

**SAML round-trip works but the user's role is wrong.** Check the role-mapping rules on the Enterprise SSO page's **Single sign-on tab**. Confirm the `groups` claim is being sent — the Okta SAML response viewer browser extension is the fastest way to see what's actually arriving — and that a rule maps the group to the role.

**Provisioning users automatically (SCIM).** Okta can create, update, and deactivate aidnn users over SCIM 2.0 in addition to SAML sign-in. The setup is provider-neutral — follow [Steps 6–9 of the Entra guide](/administration/sso-entra), substituting Okta's provisioning UI. Before you enable it, read [role precedence](/administration/sso-overview#role-mapping) and [the last-administrator rule](/administration/sso-overview#the-last-administrator-rule).

**Need to turn SAML off entirely?** Use the Admin panel **Disable SSO** action. It flips SSO off and writes an audit-log row so you can leave the IdP config in place. Re-saving the config later re-enables it. Note that it does **not** sign anyone out — existing sessions stay valid until they expire. To end a specific person's access immediately, deprovision them in your IdP.

For how SSO works in aidnn, see the [Enterprise SSO overview](/administration/sso-overview).