Skip to main content
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. 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:
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.
  1. Scroll to Attribute Statements and add at least:
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).
  1. 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.
  • 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, substituting Okta’s provisioning UI. Before you enable it, read role precedence and 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.