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

# Microsoft Entra ID SAML SSO and SCIM setup

> Configure Entra SAML sign-in and SCIM provisioning for aidnn, including domain verification, user and group mappings, and offboarding.

aidnn supports any identity provider that speaks SAML 2.0. This guide is the Microsoft Entra ID worked example; the same pattern works for Okta, AD FS, OneLogin, Auth0, JumpCloud, and most enterprise IdPs. For the protocol-level reference (claim mappings, the sign-in routing rules), see [Enterprise SSO overview](/administration/sso-overview). If you're an Okta customer, the Okta-flavored equivalent of this guide is [Okta setup guide](/administration/sso-okta).

SAML signs users in through Entra. SCIM 2.0 separately keeps aidnn users and group memberships in sync with Entra, including creating, updating, and deactivating users. Complete Steps 1–5 for SAML; continue with Steps 6–9 for automatic provisioning.

**SCIM availability:** The provisioning steps apply to aidnn deployments with SCIM enabled. If the **SCIM provisioning tokens** card is missing from Enterprise SSO, contact your aidnn administrator or support before continuing with Step 6.

This guide assumes:

* You have Entra ID admin access on the tenant where you want to enable aidnn SSO (Global Administrator, Application Administrator, or Cloud Application Administrator).
* 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.

Allow about 30 minutes for SAML setup, plus time to configure and verify SCIM provisioning. Entra synchronization runs separately from sign-in.

***

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

aidnn uses your verified email domain to route sign-ins to your Entra tenant and to check that a SAML user's email belongs to your aidnn account. Domain verification is required for SAML sign-in, including users created through SCIM; enabling SCIM does not replace this step. Before you wire Entra up, 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 (for `person@acme.com`, enter `acme.com`; for `person@mail.acme.com`, enter `mail.acme.com`).
4. aidnn returns a TXT record (`aidnn-verify=<token>`). Add it as a TXT record at the exact domain you entered (`acme.com` in this example).
5. Wait \~5 minutes for DNS propagation, then click **Recheck DNS** on the domain's row in the aidnn UI.

Public mail providers (`outlook.com`, `gmail.com`, etc.) are rejected — the resolver only routes based on domains you control. If verification fails, the UI surfaces the exact DNS lookup result.

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

***

## Step 2 — Create the Enterprise App in Entra ID

In the Microsoft Entra admin center:

1. Go to **Enterprise applications → New application**.
2. Choose **Create your own application**.
3. **Name**: `aidnn` (or your internal convention).
4. Choose **Integrate any other application you don't find in the gallery (Non-gallery)** and click **Create**.

Entra takes a minute or two to provision the registration. When it lands, open the new app and:

5. Go to **Single sign-on** in the left nav, choose **SAML** as the SSO method.
6. Under **Basic SAML Configuration**, click **Edit** and fill in:

| Setting | Value |
| - | - |
| Identifier (Entity ID) | Copy the **SP entity ID** value verbatim (see note below) |
| Reply URL (Assertion Consumer) | `https://<your-aidnn-host>/api/auth/saml/acs/<account-slug>` |
| Sign-on URL (optional) | `https://<your-aidnn-host>/signin` |
| Relay State | leave blank |
| Logout URL | leave blank |

For the **Identifier (Entity ID)**, copy the **SP entity ID** value verbatim from aidnn's admin panel SSO settings under **Service provider details**. 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.

For the **Reply URL (Assertion Consumer)**, your `<account-slug>` is the per-account string embedded in the **ACS URL** shown on that same **Service provider details** card — copy that ACS URL verbatim rather than hand-assembling it.

7. Under **Attributes & Claims**, click **Edit** and configure:

| Claim name | Source attribute |
| - | - |
| Unique User Identifier (Name ID) | `user.mail` (NameID format = Email Address) |
| `email` (custom claim) | `user.mail` |
| `name` (custom claim) | `user.displayname` |
| `groups` (group claim, optional) | `Security groups` or `All groups` |

To add `email`/`name`, click **Add new claim** under "Additional claims". To add the group claim, scroll to **Groups returned in claim**, pick your scope (Security groups, Directory roles, etc.), and set the source attribute to `Group ID` (Entra returns object IDs, not display names; the aidnn role mapping uses these IDs verbatim).

The `email` claim is required (NameID alone isn't enough — aidnn uses the explicit `email` claim for downstream resolver routing). The `name` claim is optional (admin display only). The `groups` claim is required only if you plan to map Entra groups to aidnn roles via the group-claim mapping (see Step 5 below).

8. Scroll to **SAML Certificates**. Download the **Certificate (Base64)** and copy the **Login URL** and **Microsoft Entra Identifier** from the **Set up \[aidnn]** section.

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

***

## Step 3 — Wire Entra 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 Entra:
   * **Microsoft Entra Identifier** → aidnn's **IdP entity ID** field
   * **Login URL** → aidnn's **IdP SSO URL** field
   * **Certificate (Base64)** contents → aidnn's **IdP signing certificate (PEM)** field (paste the PEM body including the `BEGIN`/`END CERTIFICATE` lines)
3. Click **Save and enable SAML** in the action bar at the bottom of the page. The form validates the certificate structurally; 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.)

***

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

1. In Entra, open your aidnn Enterprise App and go to **Users and groups**.
2. Click **Add user/group** 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 Entra. Authenticate. 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"). The most common Entra-specific cause is the certificate paste — Entra exports a base-64 string that you have to wrap in PEM headers before pasting; aidnn's form rejects an unwrapped base64 chunk. If in doubt, paste the literal text between (and including) the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines.

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.

**B2B guests and email identity.** Assigning a guest to the Entra app does not bypass aidnn's domain check. The email sent in SAML must belong to a domain verified for this aidnn account. Use the guest's actual mailbox address consistently in SAML and SCIM; do not substitute Entra's rewritten `#EXT#` UPN. Guests on unverified domains, including public Gmail/Outlook domains, cannot use this SAML setup. Confirm the guest's email and domain eligibility before assigning them.

***

## Step 5 — (Optional) Map Entra 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. If you also provision groups over SCIM (Steps 6–9), those group rules are consulted **before** the SAML assertion — see [role precedence](/administration/sso-overview#role-mapping).

* **Role from a SAML attribute.** Pick this when your IdP can be configured to emit a single string claim per user (e.g. `aidnn_role=admin`). On the Entra side, this needs a conditional-value claim ("Customize the claim" → claim value depends on `user.assignedroles` or a group-membership condition). Set the attribute name in aidnn (default `aidnn_role`), then add rows mapping each value (`admin`, `editor`, etc.) to a role.
* **Role from a SAML group claim.** Pick this when you want aidnn to consume Entra's multi-value group claim directly (the one you configured in Step 2 under "Groups returned in claim").

  In aidnn, set **Group SAML attribute name** to one of:

  * `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` — Entra's default emission. Use this if you left "Customize the name of the group claim" unchecked in Step 2.
  * `groups` — Entra's emission name when you DO tick "Customize the name of the group claim" and type `groups`. Cleaner. Recommended.

  Then add priority-ordered rows mapping each Entra Group **Object ID (GUID)** to a role. **Entra emits Group Object IDs (GUIDs), not display names** — your rows will match GUIDs like `54ed4e84-ea3a-4e90-...`. Copy the GUID from Entra → Groups → click the group → Object ID. If you want the rows readable, document the GUID-to-name mapping in your runbook.

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

***

## Step 6 — Issue an aidnn SCIM token

1. Open **Admin panel → Enterprise SSO** and find **SCIM provisioning tokens**.
2. Click **Issue token**, enter a label such as `Entra production`, and optionally set an expiry.
3. Copy the full token and save it securely before dismissing the dialog. aidnn shows it only once.

Use the token issued in the aidnn account you want Entra to manage. The token determines the destination account; the provisioning URL does not include an account slug. This is a provisioning credential, separate from the SAML signing certificate.

## Step 7 — Connect Entra provisioning and configure mappings

In the same Entra Enterprise App used for SAML, open **Provisioning**. Create a provisioning configuration if prompted, or choose **Automatic** provisioning mode. Under **Admin Credentials**, select bearer-token authentication if an authentication-method selector is shown, then enter:

| Entra setting | Value |
| - | - |
| Tenant URL | `https://<your-aidnn-host>/scim/v2` |
| Secret Token | The complete token from Step 6, without a `Bearer ` prefix |

Use your deployment's externally reachable HTTPS host. Do not append `/Users`, `/Groups`, `/api/v1`, or your account slug. Click **Test Connection**, then save. See Microsoft's [SCIM connection instructions](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups#integrate-your-scim-endpoint-with-the-microsoft-entra-provisioning-service) for portal variations.

### User mappings

Under **Mappings**, enable user provisioning and configure the following. Entra's provisioning editor uses attribute names such as `mail`, whereas the SAML claims editor uses `user.mail`.

| Entra source | aidnn SCIM target | Configuration |
| - | - | - |
| `mail` | `userName` | Required; use as the matching attribute, precedence 1. Must equal the email used for SAML sign-in. |
| `objectId` | `externalId` | Stable Entra user Object ID; retain across email changes. |
| `displayName` | `displayName` | User's display name. |
| `mail` | `emails[type eq "work"].value` | Same mailbox address as `userName`. |
| Entra's default enabled/deleted-state expression | `active` | Retain the default lifecycle mapping so deactivation sends `false`; do not replace it with a constant `true`. |

Ensure every assigned user has a populated `mail` value on a verified domain. Replace a default `userPrincipalName → userName` mapping if the UPN differs from that mailbox address. Consistent SAML and SCIM identities let provisioning attach to an existing aidnn user instead of creating a different identity.

Remove default mappings for attributes outside aidnn's supported set. Additional supported user fields are `name.givenName`, `name.familyName`, and `name.formatted`. Do not map department, manager, job title, phone numbers, addresses, or SCIM `roles`; unsupported update paths are rejected. Configure aidnn roles through Step 5 and the group mappings below.

### Group mappings (optional)

Enable group provisioning if Entra groups should manage aidnn roles. Group provisioning only affects roles when Step 5's group-to-role rules are configured — with no rules defined, aidnn syncs group membership but leaves every user's role untouched:

| Entra source | aidnn SCIM target |
| - | - |
| `objectId` | `externalId` |
| `displayName` | `displayName` |
| `members` | `members` |

The group Object IDs must match the GUIDs entered in Step 5's group-to-role rules — the same priority-ordered list serves both SCIM memberships and SAML group claims.

SCIM group rules sit **above** SAML group claims in aidnn's [role precedence](/administration/sso-overview#role-mapping), and a SCIM group change re-evaluates the affected users' roles immediately, without waiting for their next sign-in. Two consequences:

* A user whose SCIM groups match a rule has their role decided by that rule; the group claim in their SAML assertion is not consulted.
* A user who leaves the last group that granted them a role is moved to the **default role** — their SAML claims do not restore it, because aidnn has no assertion to read outside a sign-in. Their role is re-resolved the next time they sign in.

To pin one person's role so neither SCIM nor SAML changes it, use **Take over role assignment** in the Members panel; **Release** hands them back to IdP control.

Save your mappings. Microsoft's [attribute-mapping guide](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/customize-application-attributes) explains how to edit matching attributes and expressions.

## Step 8 — Start provisioning with a test assignment

1. Under Entra provisioning **Settings**, set **Scope** to **Sync only assigned users and groups**. Start with one test user and, if using group roles, one test group assigned to the Enterprise App.
2. Turn **Provisioning Status** on and save, or select **Start provisioning** if shown. Use **Provision on demand** for the test user where available; inspect **Provisioning logs** for the result.
3. In aidnn's **Members** panel, confirm the expected email appears and the role matches your rules. Check that the user created during Step 4 was matched rather than duplicated. Also provision a new test user and confirm they appear before their first sign-in.
4. Sign in as the test user through SAML. Confirm the same email and expected role after sign-in.

Group synchronization may finish after user creation. Check the group and membership results in Entra's logs before assessing group-derived roles. For provisioning controls and scope, see Microsoft's [automatic provisioning guide](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/configure-automatic-user-provisioning-portal).

If your deployment offers **Require user pre-provisioning**, enable it after the pilot succeeds when you want to reject first-time SAML users who have not yet been provisioned or invited. Otherwise, SAML can still create users at first sign-in. SCIM alone does not turn off that behavior.

## Step 9 — Verify updates and offboarding, then expand access

Use a disposable test user, not your only aidnn administrator:

* Change the user's display name in Entra, synchronize, and confirm it updates in aidnn.
* If using group roles, move the user between mapped groups, synchronize, and confirm the expected role. Removing one group membership can change a role without deactivating the user.
* Remove the user's application assignment, including any group assignment that still grants access. Wait for Entra to report successful deprovisioning. Confirm aidnn access is denied, including from an existing signed-in session.
* Reassign the user, wait for successful provisioning, and confirm they can sign in again with the expected role.

Entra sends lifecycle changes asynchronously. Access revocation in aidnn takes effect when aidnn processes the deactivation request, not merely when you edit an Entra assignment — a deactivated user's existing signed-in session stops working on their next request. Deactivation retains the user record; it does not permanently erase their data.

**One exception: the last administrator.** aidnn will not leave an account without an administrator who can still sign in. If the user Entra is deactivating is the last such administrator, aidnn accepts the request and reports success, but leaves the user active. The skip is recorded in the audit log as `admin_floor_protected`. Promote a second administrator, then retry. See [The last-administrator rule](/administration/sso-overview#the-last-administrator-rule).

**Reactivation is SCIM-only.** A user deactivated over SCIM cannot restore their own access by signing in through SAML — aidnn deliberately refuses to re-activate them on the sign-in path. Reassign them in Entra and let provisioning reactivate them.

After these checks succeed, expand the assigned users and groups. Keep provisioning running for ongoing updates and offboarding.

### Rotate the provisioning token

Issue a replacement token in aidnn, update Entra's **Secret Token**, test the connection, and save. Revoke the old token in aidnn after confirming provisioning works with the replacement. Repeat before the configured expiry. Revoking a token stops requests using that token; it does not deactivate users already provisioned, and it does not sign anyone out. Note that while no valid token exists, Entra cannot deactivate anyone either — including users you offboard in the meantime.

***

## 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 — Entra's Group ID is what you'll see, not the human group name. Use Entra's **Test SAML** UI or a SAML response browser extension to confirm what's arriving, and that a rule maps the group ID to the role.

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

**SCIM Test Connection returns 401.** Check that the complete token was pasted, has not expired or been revoked, and was issued on this aidnn deployment. Issue a replacement if necessary.

**SCIM Test Connection returns 404 or an HTML page.** Confirm the URL ends in `/scim/v2` with no trailing path (no `/Users`, no `/api/v1`) and points at the externally reachable aidnn API host for your deployment, not the app URL. Ask aidnn support to confirm the external provisioning endpoint if the URL is correct.

**Provisioning returns 400 or an unsupported attribute error.** Inspect the failed attribute in Entra's provisioning logs. Remove unsupported mappings and check that `userName` and the work email contain the intended mailbox address.

**Provisioning returns 409.** The email or external identifier may conflict with an existing user or account. Verify the mappings and destination account; contact aidnn support to resolve ownership instead of deleting users to retry.

**A provisioned user cannot sign in.** Confirm SAML works independently, the SCIM `userName` matches the SAML email, and that exact email domain is verified for this aidnn account. Provisioning success does not bypass SAML domain verification.

**An unassigned user still has access.** Check whether another assigned group keeps the user in scope, whether provisioning is running, whether Entra has successfully delivered a deactivation, and — if the user is an administrator — whether they are the account's last one. aidnn reports success but does not deactivate the last administrator who can still sign in; look for `admin_floor_protected` in the audit log and see [The last-administrator rule](/administration/sso-overview#the-last-administrator-rule). Stopping provisioning or revoking its token prevents future offboarding updates; neither action removes existing users' access.

For protocol-level questions and the full audit-event glossary, see [Enterprise SSO overview](/administration/sso-overview).