Authentication settings overview

How the Domains, Single sign-on, SCIM provisioning, and Local accounts cards work together, what the plan requires, how to verify a domain, and what forcing single sign-on does.

Written for
admin
Roles
owner, admin
Requires
Owner or Admin; Business plan or trial to set anything up; Browser session with a recent re-authentication
Feature
authentication

By default everyone logs in to SAQ with a password or a passkey, owners and admins add an authenticator code, and regular client users get a magic link. Settings → People → Authentication is where a workspace adds enterprise sign-on on top: verified domains, one OpenID Connect connection, and SCIM provisioning. The page has four cards, and each card depends on the one above it. This page explains how they fit together; the connection and SCIM each have their own page.

Before you start

  • You need the Owner or Admin role. Every change here asks you to confirm your identity.
  • Setting anything up requires the Business plan or higher; the trial includes it. On a lower plan the cards are locked: "Included from the Business plan. What is already set up keeps working and can be turned off or removed; nothing new can be added on the current plan." An active connection keeps logging people in after a downgrade, and SCIM can still deactivate users but not create them.
  • SAQ supports OpenID Connect only. There is no SAML.

The four cards

Card What it does Depends on
Domains Proves by DNS that the workspace controls a domain. Nothing.
Single sign-on (OIDC) One connection to an identity provider. Logs in people whose address is on a verified domain, or who are already linked. A verified domain for anyone not yet linked.
SCIM provisioning Lets the identity provider create, update, and deactivate workspace users. A verified domain: SCIM only provisions addresses on one.
Local accounts Shows who can still use a password or passkey here. Which domains are forced to single sign-on.

Verify a domain

  1. Under Domains, select Add a domain, enter the domain (for example acme.example), and select Add.
  2. Publish the TXT record the card shows at your DNS provider: name _saq.<domain>, value saq-verify=<token>. The token is specific to this workspace and domain.
  3. Select Verify now. The status moves from Pending to Verified; if the record is not found yet, the card says why under "Not verified yet".

Verified domains are re-checked weekly, and a record published later is picked up on its own. If the record disappears, the domain keeps its status for a 7-day grace period: the card shows "The record has not resolved since {date}. Force SSO is turned off after 7 days.", the owners receive an email, and the check runs daily. When the grace period runs out, Force SSO is turned off for the domain, the domain is marked Failed, and the owners are told again. Restore the record and select Verify now to recover. Two workspaces can each verify the same domain.

Removing a domain turns Force SSO off for it first; members keep their accounts.

Force single sign-on

Force SSO is a per-domain switch on the Domains card. It requires a Verified domain and an Active connection; until the connection is Active the switch is inert. To turn it on, your own session must have come through this workspace's single sign-on ("Log out and log in with SSO first."), and you confirm your identity. The confirmation names how many current members are on the domain.

From that moment, for people whose address is on the domain:

  • Only a session that came through the connection can enter this workspace. Password and passkey sessions are locked out of the workspace and sent to the identity provider; a password session is never upgraded silently.
  • Their personal API tokens are revoked, and creating a new one requires a session that came through single sign-on.
  • The login page sends their address straight to the identity provider.

Forced SSO is a property of this workspace, not of the person: the same account can still use a password in another workspace that does not force the domain. Turning it off, removing a domain, or deactivating or removing the connection needs an owner or admin with a recent re-authentication of any kind, not an SSO session, so the way back never depends on the provider. If the provider becomes unreachable, the connection is marked Error and forced SSO is inert until an admin tests it again. See Set up single sign-on.

Local accounts

The Local accounts card sums up the result: "Password and passkey login are available to everyone whose domain is not forced to single sign-on." It lists the forced domains, if any, and the number of workspace users. Exemptions from forced SSO (break-glass accounts) do not exist yet.

Two-factor authentication

Owners and admins must have two-factor authentication (an authenticator app or a passkey) to enter a workspace; members and client users are encouraged but not required. Single sign-on can satisfy this when the connection has an MFA assurance rule the identity provider's token meets (for Microsoft Entra ID, amr contains mfa). Otherwise owners and admins finish with their local authenticator code after the identity-provider round trip. The assurance counts only in the workspace whose rule was met.

Common problems

The cards are locked. The plan does not include single sign-on. An owner can change it under Settings → Organization.

"Verify the domain first." Force SSO and SCIM provisioning need a Verified domain.

"Log in through this workspace's single sign-on before making it required." Log out, log in with Continue with {workspace} SSO, and try again.

"The verification record is missing. Restore it before making sign-on required." The domain is in its grace period. Republish the TXT record and select Verify now.

Everyone is locked out because the identity provider is down. After three failed round trips in fifteen minutes the connection is marked Error and forced SSO stops applying, so owners and admins can log in with a password to fix it.

  • Set up single sign-on (OIDC) Connect a workspace to Microsoft Entra ID or any OpenID Connect provider, test and activate the connection, and understand who it logs in and how MFA is handled.
  • Set up SCIM provisioning Let your identity provider create, update, and deactivate workspace users through SCIM 2.0, with a default role and a group-to-role mapping.
  • Plan, seats, and subscription The plans and what each includes, the subscription states and the 30-day trial, what read-only mode means, how seats are counted, and how to subscribe, change plan, or be invoiced.
  • API tokens and agent accounts The two kinds of API keys in SAQ, personal tokens and agent accounts, their scopes, restrictions, and expiry, and how owners and admins oversee and revoke them.
  • First login Accept your invitation, choose a login method, set up two-factor authentication if you are an Owner or Admin, and find your workspace.
  • Owner and Admin Everything an Owner or Admin configures in SAQ, with links to each task, the differences between the two roles, and the two-factor requirement.