Single Sign-On

Single sign-on lets your people sign in to DocAI Fabric through your organization's identity provider, with its passwords, its multi-factor authentication and its access policies. Groups in the identity provider decide which DocAI Fabric groups people join, and so which roles they have.

DocAI Fabric speaks OpenID Connect, which Microsoft Entra ID, Okta, AD FS (Windows Server 2016 and later), Ping, OneLogin, JumpCloud, Google and Keycloak all support. This page walks through Microsoft Entra ID in full; the other providers section lists what changes for the rest.

Setting it up takes the Manage single sign-on permission (tenant.manage_sso) for the whole tenant. Administrators have it. The settings are on the Security page, Single Sign-On tab.

How access works

Your identity provider decides who is in which group. DocAI Fabric decides what each group may do.

Identity provider group  →  DocAI Fabric group  →  roles
"Finance Reviewers"         "Invoice Reviewers"     Reviewer on project Invoices
"DocAI Admins"              "SSO Admins"            Admin, whole tenant

1. In DocAI Fabric, create a group for each kind of access and give it roles, for the whole tenant or for chosen projects (Team page, Groups tab; see Groups).
2. In your identity provider, put people in groups as you normally would.
3. On the Single Sign-On tab, map each identity provider group to a DocAI Fabric group.

At every sign-in DocAI Fabric reads the groups the identity provider sends and updates the person's membership. Add someone to the group in your identity provider and they have the access at their next sign-in; remove them and they lose it at their next sign-in.

A connection has one of two ways of managing access (Who manages access in the connection settings):

Setting	What happens at sign-in	Use it when
The identity provider (recommended)	People join the mapped groups their token names and leave the mapped groups it no longer names. Someone whose token names no mapped group cannot sign in.	You want joiners, movers and leavers handled in one place, your identity provider.
DocAI Fabric	A new person joins the Default group once. After that, administrators manage their groups on the Team page; the identity provider only proves who they are.	Your identity provider cannot send groups, or you prefer to manage access here.

Groups you did not map are never touched by sign-in, so you can still add people to other groups by hand.

On the Team page, Groups tab, a group that sign-in manages shows Managed by and the connection's name. You can still add someone to it by hand: a person who signs in another way, such as a guest with a password, stays in it; a person who signs in through the connection is added or removed again at their next sign-in, according to their groups in the identity provider.

Administrators through a group

A group can hold the Admin role, so an identity provider group can make people administrators. Three rules keep that safe:

• Only an administrator can give a group Admin, or map an identity provider group to a group that holds a role for the whole tenant.
• The tenant's administrators get an email when a group receives Admin and whenever someone joins such a group, including through sign-in.
• The tenant always keeps at least one administrator who holds Admin directly, not through a group. Sign-in never removes that person, and removing, deactivating or taking Admin from the last one is refused. Keep this account signing in with a password, so you can still get in if the identity provider is down or misconfigured.

Also match group names (under Advanced settings) puts people in a DocAI Fabric group whose name equals a group value the identity provider sends, without a mapping. It never reaches a group that holds a role for the whole tenant: map those explicitly.

Before you start

• An email domain you control. Single sign-on works for people whose email address is at a domain you have proven is yours. Your users' sign-in names must be at that domain. Addresses at a shared domain that nobody can publish DNS records for, such as onmicrosoft.com, cannot be used.
• Access to your DNS provider, to publish one TXT record.
• Admin access to your identity provider, to register an application.
• An administrator who signs in with a password stays in DocAI Fabric as your way back in (see above). If you later require single sign-on, make them a break-glass exemption.

Step 1: Verify your email domain

1. On the Single Sign-On tab, under Email Domains, enter your domain (for example example.com) and select Add domain.
2. The page shows a TXT record: its name is _docaifabric.<your domain> and its value starts with docaifabric-domain-verification=. Publish it at your DNS provider.
3. Select Verify. DNS changes can take a few minutes to appear; if it does not pass at once, try again later.

Add every domain your people sign in with. Keep the record published: DocAI Fabric looks it up again about once a day.

• If it is missing, the tenant's administrators get an email and the domain shows Record missing on the Single Sign-On tab, with the record to publish again.
• If it is still missing at three daily checks in a row, the domain is Suspended: nobody new can sign in through it, and people already signed in through it before keep working.
• Once the record is back, select Verify (or wait for the next daily check) and the domain is in use again.

A DNS server that does not answer does not count as a missing record.

Step 2: Register DocAI Fabric in Microsoft Entra ID

In the Microsoft Entra admin center:

1. App registrations → New registration. Give it a name (for example DocAI Fabric), choose Accounts in this organizational directory only, and leave the redirect URI empty for now. Register.

2. On the app's Overview, copy the Application (client) ID and the Directory (tenant) ID.

3. Certificates & secrets → New client secret. Copy the secret's Value at once (Entra shows it only once). The Secret ID next to it is not the secret.

4. Token configuration → Add groups claim. Choose which groups are sent:

   • Groups assigned to the application, if your Entra plan lets you assign groups to applications. This sends only the groups that matter to DocAI Fabric and is the cleanest choice.
   • Security groups, if it does not (the free plan shows Groups are not available for assignment due to your Active Directory plan level). This sends every security group the person belongs to.

   Under ID, choose Group ID. Save.

The redirect URI is added in step 4, once DocAI Fabric has shown it to you.

Step 3: Add the connection in DocAI Fabric

On the Single Sign-On tab, select Add connection:

Field	Value
Name	Shown to people as they sign in, for example Contoso sign-in.
Issuer URL	https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0
Client ID	The Application (client) ID.
Client secret	The secret's Value. It is stored encrypted and never shown again.
Domains	The domains you verified in step 1.
Who manages access	The identity provider, unless you chose otherwise above.

Advanced settings can stay as they are for Entra:

Setting	Default	Change it when
Sign-in address	Made from the name	You want a different address for your people's sign-in link.
Group claims	groups, roles	Your provider sends groups in a claim with another name.
Email claim	email	Your provider puts the address elsewhere. If the token has no email, the sign-in name (preferred_username) is used when it is an email address.
Require multi-factor evidence	Off	You want DocAI Fabric to refuse a sign-in whose token does not show multi-factor authentication (see MFA).
Session length (hours)	12	Between 1 and 24. After it, people sign in again through the identity provider.

Save. The connection starts as a Draft: nobody can use it yet.

Step 4: Register the redirect URI in Entra

Select the new connection's row. Under Values for Your Identity Provider, copy the Redirect URI.

In Entra, open the app registration, Authentication → Add a platform → Web, paste the redirect URI and save. Leave the implicit grant and hybrid flow options unticked.

The Sign-in URL shown next to it takes people straight to your identity provider. You can give it to your people or add it to your organization's app launcher.

Step 5: Map your groups

In Entra, open each group that should have access and copy its Object ID.

In DocAI Fabric, with the connection selected, under Group Mappings select Add mapping:

• Identity Provider Value: the group's Object ID.
• Label: a name you will recognize, such as the Entra group's name. It is for you only.
• DocAI Fabric Group: the group that holds the roles these people should have.

You do not have to copy IDs by hand: the test sign-in in the next step lists every group value Entra sent, each with Map to group.

Step 6: Test, then activate

1. Select Test sign-in on the connection and sign in at Entra as a person who should have access. Use a private browser window if you are already signed in to Entra as someone else.
2. The test report shows whether the sign-in passed and what it would do: the account it would create or link, the groups the person would join and leave, the group values not mapped, whether multi-factor authentication was reported, and the claims received. Nothing is changed by a test.
3. Fix anything the report shows (see Troubleshooting) and run the test again until it passes.
4. Select Activate. A connection can only be activated after a test sign-in passed.

Your people can now sign in: on the sign-in page they choose Sign in with single sign-on and enter their work email, or open the Sign-in URL directly.

Accounts

• New people get an account at their first sign-in. It has no password: they always sign in through your identity provider, and password reset is refused for it.
• People who already have an account with the same email are linked to the identity provider at their first sign-in through it. They keep their password, but once you require single sign-on it lets them in only if they are exempt.
• Someone who belongs to several tenants keeps one account. Each tenant's mappings decide their groups in that tenant.

Multi-factor authentication

Your identity provider decides when to ask for a second factor; DocAI Fabric never sees or stores it. Enforce MFA in the identity provider: in Entra, with Conditional Access or security defaults.

If you also want DocAI Fabric to check, turn on Require multi-factor evidence. A sign-in is then refused unless the token shows multi-factor authentication (its amr claim names a second factor, or its acr claim has a value you set). Run a test sign-in first: the report says whether your provider reported multi-factor authentication. If it did not, leave the setting off and rely on the provider's own policy.

When someone leaves

• Removed or disabled in the identity provider: they cannot sign in through single sign-on again. A session they already have ends at the latest after the connection's session length (12 hours by default). Someone who also has a password can still sign in with it, unless you require single sign-on and they are not exempt.
• To end their access at once: on the Security page, Sessions tab, end all their sessions, then remove them from the tenant on the Team page.
• Personal API keys and connected AI agents that act as the person pause once they have gone the set number of days without signing in through single sign-on, if single sign-on is their only way in (see API keys and AI agents). Remove them from the tenant to stop those at once. Integration keys belong to the tenant, not to a person, and are not affected by single sign-on.

Require single sign-on

Turning on single sign-on does not turn password sign-in off by itself. To make your identity provider the only way in, and so let its multi-factor authentication and access policies apply to everyone, switch on Require Single Sign-On on the Single Sign-On tab.

While it is on:

• Sign-in. People sign in only through one of your tenant's connections, or a connection set up for the whole deployment. Password and Google sign-in are refused for them, and so is a password reset. Someone who belongs to several tenants can still use a password for the tenants that do not require single sign-on.
• Sessions. When you switch it on, sessions made another way end at once, except those of exempt people. Yours ends too unless you signed in through single sign-on.
• New people join only through single sign-on. Create user and Invite user on the Team page are turned off, and invitations already sent stop working. With access managed by the identity provider, adding someone to a mapped group is how they join.
• Exempt people sign in as before: see Exemptions.

To switch it on, you must first prove that single sign-on works for you: run Test sign-in with your own account through an active connection, and switch it on within 30 minutes. This keeps you from locking yourself out.

Switching it off lets people with a password use it again. The administrators get an email when it is switched off.

Exemptions

These people can still sign in without single sign-on:

• The owner of the tenant, always. The owner needs no exemption.
• Break-glass administrators, kept for when the identity provider is unavailable or misconfigured. Add at least one, sign them in with a strong password, and keep the credentials safe. The administrators get an email when a break-glass exemption is added and every time a break-glass administrator signs in without single sign-on.
• Guests: members whose email is not at your domains, such as a consultant. A guest must already be a member to be exempted. To bring in a new guest, switch the requirement off, invite them, exempt them once they have joined, and switch it back on.

Add exemptions under Exemptions on the Single Sign-On tab, with a note on why. Removing an exemption ends the person's sessions made another way. Every sign-in through an exemption is recorded in the audit log.

API keys and AI agents

	Integration API key	Personal API key	AI agent connected by URL (Claude, Codex)
Acts as	The tenant, not a person	Its owner, with their current permissions	The person who approved the connection, with their current permissions
Affected by single sign-on	No	Yes, see below	Yes, see below
Created or connected by	An administrator	The person, while signed in	The person, approving the connection in the browser; if they are not signed in, they sign in through single sign-on first

Integration keys are the right choice for systems such as an ERP feed or a scheduled job: no person signs in for them, so single sign-on never affects them.

A personal key or an agent pauses when the person it acts as signs in only through single sign-on and has not done so for longer than the number of days set under Pause personal keys and agents after this many days without single sign-on (7 by default, between 1 and 30). That covers everyone while single sign-on is required, except exempt people, and people who have no password even while it is not required. A paused key or agent is not disconnected: calls are refused until the person's next sign-in through single sign-on, which restores it. The Agents & API page shows such a key as Stopped, with the reason that its person has not signed in through single sign-on recently.

This is how a person removed in your identity provider loses their keys and agents even if nobody removes them in DocAI Fabric, as long as single sign-on is their only way in: they can no longer sign in, so their keys pause within the set number of days. Someone who still has a password and is not bound by a requirement keeps their keys until you remove them. When you switch the requirement on, the keys and agents of people who have never signed in through single sign-on pause at once; ask your people to sign in through it once.

Each call is also checked against the person's current state: removing someone from the tenant, deactivating them or taking away a role takes effect immediately.

Other identity providers

Steps 1, 3, 5 and 6 are the same for every provider. What changes:

Provider	Issuer URL	Groups
Okta	https://<your-org>.okta.com (or your authorization server's issuer)	Add a groups claim to the ID token with a filter, for example Starts with DocAI-. Okta sends group names, so mappings read naturally.
AD FS	https://<your-adfs-host>/adfs	Send group names or SIDs in a groups claim with a claim rule.
Google Workspace	https://accounts.google.com	Google's token carries no groups: choose DocAI Fabric under Who manages access and set a default group.
Others (Ping, OneLogin, JumpCloud, Keycloak)	The issuer from the provider's OpenID Connect settings	Send groups or roles in a claim and name it under Group claims if it is not groups or roles.

Register the redirect URI from step 4 as an allowed redirect (or callback) URI of a web application, with the authorization code flow.

Entra app roles are an alternative to groups. Define roles in the app registration (App roles, for example DocAI.Reviewer), assign people or groups to them under the enterprise application, and map the role values. They arrive in the roles claim, which DocAI Fabric reads by default. Assigning people (not groups) to app roles works on every Entra plan.

Self-hosted deployments

On a deployment you run yourself, the operator can also set up a connection for the whole deployment from the command line, with da admin sso (see Set up single sign-on (CLI)). People then see Sign in with and the connection's name on the sign-in page. Each tenant's administrators still map groups for their own tenant on the Single Sign-On tab.

Troubleshooting

The test report names the reason a sign-in did not complete; people signing in see a short message instead. Both are listed here.

The assistant can help too: with the Manage single sign-on permission, ask it why someone cannot sign in or which identity provider group gives which access. It reads your connections, mappings, last test, domains and settings, but it cannot change them: changes are made on the Single Sign-On tab.

Message or reason	What to check
Single sign-on cannot add new people right now (domain_suspended)	The domain's TXT record has been missing for days. Publish it again (the Single Sign-On tab shows it) and select Verify. People who signed in before are not affected.
Single sign-on is not set up for this email address	The person's email is not at one of the connection's verified domains, or the sign-in name in Entra is at another domain (for example onmicrosoft.com).
Your account is not allowed to use DocAI Fabric yet	With access managed by the identity provider, none of the person's groups is mapped. Check the groups claim in Entra (step 2) and the mappings (step 5); the test report lists the values it received.
The identity provider sent no group values	The groups claim is missing: add it in Entra under Token configuration. With Groups assigned to the application, the group must also be assigned to the enterprise application.
Your identity provider sent too many groups	Entra sends at most 200 groups in a token. Send only the groups assigned to the application, or use app roles.
Your organization requires multi-factor authentication	Require multi-factor evidence is on and the token did not show a second factor. See MFA.
Your identity provider did not confirm your email address	The provider marked the email as unverified. Fix it in the provider.
An error from Entra before you come back (for example AADSTS50011)	The redirect URI in Entra does not match the one shown in DocAI Fabric exactly.
token_exchange_failed	Entra refused the client secret: it is wrong or expired. Paste the secret's Value, not its ID, in the connection settings.
issuer_mismatch or idp_metadata_invalid	The Issuer URL is not exactly the one the provider publishes. For Entra it ends in /v2.0 and contains the Directory (tenant) ID.
audience_mismatch	The Client ID in the connection is not the one of the app registration that signed the person in.
Single sign-on is not available for this organization right now	The connection is a draft or disabled. Activate it after a passing test.
The sign-in link expired or was opened in another browser	The sign-in must finish in the browser that started it, within a few minutes. Start again.
Your organization requires single sign-on (at password or Google sign-in)	Single sign-on is required and the person is not exempt. They choose Sign in with single sign-on.
Invitations no longer apply	The invitation was sent before single sign-on was required. The person signs in through single sign-on instead.
A personal API key or agent is refused with sso_reauth_required	The person it acts as has not signed in through single sign-on recently. Their next sign-in restores it. See API keys and AI agents.

Every sign-in, refused or not, and every change to the connections, domains and mappings is recorded in the audit log (sso.login.succeeded, sso.login.failed, sso.user.provisioned, sso.config.updated, sso.group_mapping.updated). Changes to the requirement and the exemptions are recorded as sso.config.updated, and a sign-in through an exemption as auth.local_login.used_while_sso_enforced.