Skip to main content
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. If you’re an Okta customer, the Okta-flavored equivalent of this guide is Okta setup guide. 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:
  1. Go to Single sign-on in the left nav, choose SAML as the SSO method.
  2. Under Basic SAML Configuration, click Edit and fill in:
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.
  1. Under Attributes & Claims, click Edit and configure:
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).
  1. 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.
  • 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: 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 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. 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: 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, 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 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. 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. 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. 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.