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.

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

Single sign-on lets workspace users log in through your identity provider instead of a SAQ password. A workspace has one OpenID Connect connection, configured on the Single sign-on (OIDC) card under Settings → People → Authentication. SAQ has a preset for Microsoft Entra ID and works with any other provider that implements OpenID Connect. SAML is not supported.

Before you start

  • You need the Owner or Admin role and the Business plan or the trial.
  • Verify your email domain first (see Authentication settings overview). The connection only signs in addresses on a verified domain, unless the person is already linked.
  • You need permission to register an application at the identity provider.

Register the application

SAQ uses the authorization-code flow with PKCE. Register a web application at the provider with the redirect URI the card shows under Redirect URI to register: https://saq.no/api/auth/sso/callback. Create a client secret and note the client id.

Microsoft Entra ID

  1. In the Entra admin center, open App registrations → New registration. Redirect URI type Web, value as above.
  2. Under Certificates & secrets, create a client secret. Paste it into SAQ; it is stored encrypted and never shown again.
  3. Under Token configuration, add the email optional claim to the id token. If groups should map to roles, add the groups claim too. Entra sends group object ids unless the app is configured for names; map whatever it sends.
  4. To let Entra's MFA satisfy SAQ's requirement for owners and admins, keep the MFA assurance rule at amr / mfa and require MFA for the app in Conditional Access.
  5. Recommended: add the auth_time optional claim. SAQ asks for a fresh identity-provider login before sensitive changes; with auth_time, an interactive login counts from that moment. Without it, the first protected change after logging in asks for another identity-provider login.

Group overage: above roughly 150 groups, Entra leaves the groups out of the token. SAQ then treats the groups as unknown, keeps the last groups it saw, and the connection test says so under Groups. Restrict the claim to groups assigned to the application, or use app roles.

Fields

Field Meaning
Provider Microsoft Entra ID or Generic OpenID Connect.
Entra tenant id Entra only: the directory (tenant) id or a verified tenant domain. The issuer is derived from it.
Issuer Generic only: the issuer URL (https, no query or fragment); discovery is read under it.
Client id From the app registration.
Client secret Write-only. Leave empty on later saves to keep the stored secret.
Scopes Requested from the provider; the preset fills the usual values.
Claim mapping Email claim, Name claim, Groups claim. Dotted paths reach nested claims. With the Entra preset, preferred_username is used when the email claim is absent.
MFA assurance rule A Claim and Accepted values. When the id token's claim contains one of the values, the session counts as MFA-verified. Empty means owners and admins still need local two-factor.
Create accounts on first login (JIT provisioning) Creates a workspace user for an unknown address on a verified domain.

Activate the connection

  1. Select Save connection. The connection is a Draft.
  2. Select Test connection. A popup runs a real round trip as you and shows the subject, name, groups, MFA assurance, and the claims received.
  3. When the round trip succeeds, the connection becomes Active and is offered on the login page as Continue with {workspace} SSO.

A failed test on a Draft marks it Error with the reason. A failed test on an Active connection records the error but leaves it Active, so a broken test never switches forced SSO off by accident. Changing the issuer, client id, or secret puts the connection back to Draft; test again. Only owners and admins can test, and your session must meet the workspace's own entry rules (two-factor, and single sign-on if your domain is forced).

Who an assertion logs in

  1. An account already linked to the provider's subject wins.
  2. Otherwise the address counts only when it is on a domain this workspace has verified. Other addresses are refused: "This workspace has not verified the domain of your address, so it cannot sign you in through single sign-on."
  3. An unknown address on a verified domain is refused unless JIT provisioning is on. JIT creates the person as a Member; the group → role mapping on the SCIM card can raise the role from the token's groups claim. Administrative access still waits until two-factor is satisfied.
  4. JIT joins a person on their first login only. Someone removed from the workspace, or deactivated by SCIM, is not re-joined; invite them or push them through SCIM.
  5. A client user of the workspace logs in through the connection but stays a client user. Agent accounts never log in this way.

Two-factor for owners and admins

If the id token satisfies the MFA assurance rule, the session counts as MFA-verified in this workspace. If there is no rule, or the claim is missing, owners and admins enter their local authenticator code after the round trip, as with a password login. The connection test shows which applies: "Satisfied by the identity provider" or "Not satisfied; owners and admins still need local two-factor".

When the provider cannot be reached

When real logins fail three times in a row within fifteen minutes because the provider is unreachable, the connection is marked Error, the owners are emailed, and forced SSO is inert until an admin tests the connection again. A declined login or an error answered by the provider never counts, so a working connection cannot be downgraded from outside.

Deactivate or remove

Deactivate puts the connection back to Draft: "Forced domains are inert until it is Active again." Remove deletes it; Force SSO is turned off on every domain first, and linked people keep their accounts and local logins. Both need a recent re-authentication of any kind, not an SSO session.

Common problems

"There is no account for this address, and this workspace does not create accounts on first login." Turn on JIT provisioning, or invite the person.

"The identity provider did not send an email address." Add the email claim to the id token (Entra: optional claim email) or fix the Email claim mapping.

"The discovery document names a different issuer." The issuer you entered must match the issuer in the provider's discovery document exactly.

"The identity provider did not sign you in again, so the change was not confirmed." A protected change asked for a fresh login, but the provider reissued from its own session. Try again, or confirm with a password or passkey.

  • 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.
  • 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.
  • Manage members and invitations Invite workspace users by email, set and change their role, remove them or let them leave, and understand how seats are counted.
  • 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.
  • 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.