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

# Enterprise SSO overview

> How SAML single sign-on works in aidnn — domain-based sign-in routing, claim mapping, and the setup path for any SAML 2.0 identity provider.

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**: users start at aidnn, enter their email, and aidnn redirects them to your IdP. There is no separate aidnn tile to set up in your IdP's app catalog.

## What aidnn reads from the SAML assertion

| Claim | Required | Purpose |
| - | - | - |
| `email` | Yes | The user's unique identifier in aidnn. |
| `name` | No | Display name only. |
| `groups` or a role attribute | No | Drives role mapping (see below). |

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

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

* [Okta setup guide](/administration/sso-okta)
* [Microsoft Entra ID setup guide](/administration/sso-entra)

## 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](/administration/sso-entra).