Skip to main content
aidnn supports single sign-on through any identity provider that speaks SAML 2.0 — Okta, Microsoft Entra ID, AD FS, OneLogin, Auth0, JumpCloud, and most enterprise IdPs. This page explains how SSO works in aidnn; the step-by-step provider guides are linked at the bottom.

How sign-in routing works

aidnn routes sign-in attempts by email domain:
  1. An admin claims and verifies the email domain your employees use (for example acme.com) by adding a DNS TXT record.
  2. Once a domain is verified, anyone signing in with an email at that domain is routed to your identity provider to authenticate.
  3. SAML is optional and additive — users whose email is not in a verified domain keep their existing sign-in method (password, magic link, or Google). Enabling SSO for your domain never locks other accounts out of aidnn.
Sign-in is SP-initiated by default: users start at aidnn, enter their email, and aidnn redirects them to your IdP. aidnn can also accept IdP-initiated sign-in, where users launch aidnn from a tile in your identity provider, but that is off until you turn it on — see below.

IdP-initiated sign-in (app tiles)

By default aidnn accepts only sign-ins that started at aidnn. If a user clicks an aidnn tile in Okta’s dashboard or Microsoft’s My Apps and your identity provider sends the assertion directly, aidnn rejects it as IdpInitiatedNotAllowed. To allow it, turn on Allow IdP-initiated sign-in under Sign-in options on the Enterprise SSO page. Why it is off by default. On the SP-initiated path aidnn ties the assertion to the browser that began the sign-in, by matching a one-time value it issued against the one your IdP echoes back inside the signed assertion. An IdP-initiated assertion has no such value, so that tie cannot be checked, and someone who obtains a valid assertion can cause a victim’s browser to sign in as them (login CSRF). Every other protection still applies — signature, audience, timing, the signed recipient binding to your exact aidnn URL, and one-time-use replay protection. Only the browser binding is relaxed. Both sides have to agree. Turning the setting on tells aidnn to accept an unsolicited assertion; it does not make your IdP send one. Your IdP decides that: You may not need it. Setting the Entra Sign-on URL to https://<your-aidnn-host>/signin gives users a working tile that runs the ordinary SP-initiated flow. They enter their email once; because they are already signed in to the IdP, the redirect back is silent.

What aidnn reads from the SAML assertion

The first time a verified user signs in through SAML, aidnn creates their account automatically (just-in-time provisioning) from the email claim.

Role mapping

aidnn resolves each user’s role in a fixed order of precedence. The first rule that produces a role wins:
  1. A role set locally in the Members panel (Take over role assignment). IdP updates never override it until an admin releases the user back to IdP control.
  2. SCIM group membership, if you provision groups over SCIM and have group-to-role rules configured. The rule highest in your priority list wins.
  3. A group claim in the SAML assertion — your IdP’s multi-value groups claim, matched against the same priority-ordered rules (first match wins).
  4. A role attribute in the SAML assertion — a single string claim per user (e.g. aidnn_role=admin) mapped to an aidnn role.
  5. The configured default role, when nothing above matches.
You can configure any combination of these, or none. Two consequences are worth knowing before you enable SCIM group provisioning:
  • SCIM group rules outrank your SAML group claim. For a user whose SCIM groups match a rule, the group claim in their assertion is not consulted.
  • Roles are re-evaluated when SCIM group membership changes, not only at sign-in. A user who leaves the last group that granted them a role is moved to the default role. The one exception is the account’s last remaining administrator — see The last-administrator rule.

The last-administrator rule

aidnn will not leave an account with no administrator who can still sign in. If your IdP tries to deactivate, remove, or demote the last such administrator, aidnn accepts the request and reports success to your IdP, but does not apply the change — that account would otherwise have no one able to reach the SSO configuration or the provisioning token, and recovery would need aidnn support. The skip is recorded in the audit log as admin_floor_protected. If a deprovisioning or role change appears to have succeeded in your IdP but had no effect in aidnn, this is the first thing to check. Promote a second administrator, then retry. Keep at least two administrator accounts so routine offboarding never hits this rule.

Setup at a glance

  1. Claim your domain in aidnn and verify it with a DNS TXT record.
  2. Create a SAML app in your identity provider and exchange metadata — aidnn’s ACS URL and SP entity ID for your IdP’s sign-on URL, issuer, and signing certificate.
  3. Save and enable SAML in aidnn — this generates the per-account service-provider keypair and turns sign-in on.
  4. Test a round-trip with one assigned user before rolling out.
  5. (Optional) Map your groups or a role attribute to aidnn roles.
Provider-specific walkthroughs:

Turning SSO off

The Disable SSO action in the admin panel turns SAML sign-in off for the account and records the change, while leaving your IdP configuration in place. Re-saving the configuration later re-enables it. Disable SSO does not sign anyone out. Anyone already signed in keeps their session until it expires; disabling SSO changes how people sign in from that point on, not who is currently signed in. This matches Slack, Linear, Notion, Okta, and GitHub, which all treat “disable” and “revoke sessions” as separate actions. To cut off a specific person immediately, deprovision them in your IdP — see the Entra guide’s offboarding steps.