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 higher (not the 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, which links to this page under "Read the single sign-on guide". 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 higher. The trial shows the card disabled.
  • 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 and note its expiry date (Entra allows at most 24 months). Paste the secret into SAQ together with the date; the secret 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, request the amr optional claim in the ID token. Entra's v2.0 tokens, which SAQ uses, leave amr out unless it is requested, and without it the MFA assurance rule never matches: the round trip succeeds, but owners and admins are still asked for their SAQ authenticator code. The Token configuration picker does not list amr, and nothing in the tenant needs enabling; add it through the app registration's Manifest instead. Under Manage → Manifest, add the entry below to optionalClaims (keep any entries already there, such as email and auth_time), then select Save:

    "optionalClaims": {
      "idToken": [{ "name": "amr", "essential": false }]
    }
    

    Then require multi-factor authentication for the application in Conditional Access, and keep the rule at amr / mfa. The connection test reports the outcome under MFA assurance and lists the claims received; if amr is not among them, the manifest entry is still missing or not saved.

  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.
Client secret expires The date the provider shows for the secret. Optional, but with it the owners are emailed 30 days, 7 days, and 1 day before, and the card shows the date. The date is saved on its own: change it with Client secret left empty and the stored secret and the status stay as they are. Saving a new secret without a date clears the old date. A partly typed date is refused: "Enter a complete date, or leave the field empty to keep the stored date unchanged."
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: "Connection saved. Run a test to activate it." (A later save that changes neither the issuer, the client id, nor the secret keeps the status, and an Active connection then says only "Connection saved.")
  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).

When the client secret expires

Identity providers issue client secrets with an expiry, and once it passes every login through the connection fails at the token exchange. Record the date under Client secret expires when you save the secret. The card then shows "The client secret expires {date}." (in warning colour inside the last 30 days, and "The client secret expired {date}." once it has passed), and the workspace owners receive an email 30 days, 7 days, and 1 day before the date: "The single sign-on secret for {workspace} expires in {count} days". Each reminder is sent once; entering a new secret or correcting the date starts the reminders over. To correct the date alone, change Client secret expires with Client secret left empty and select Save connection: the stored secret is kept and an Active connection stays Active, with no new test needed.

To renew: create a new secret at the provider, paste it under Client secret with its new date, select Save connection (the connection returns to Draft), and select Test connection to make it Active again. Do this before the old secret expires: while the connection is Active and a domain is forced, people on that domain can enter the workspace only through the connection, so an expired secret locks them out until an owner or admin whose address is not on a forced domain saves the new one.

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", and in the second case why: no rule is set, the claim was not in the token at all (for Entra, the amr optional claim is missing), or the claim was there but none of its values matched (the provider did not require a second factor for that login, or the accepted values are wrong).

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.

I log in through Microsoft Entra ID with MFA and SAQ still asks for my authenticator code. Run Test connection and read the MFA assurance line. "The id token carried no such claim" means the amr optional claim is not configured on the app registration; add it through the Manifest as described above (the Token configuration picker does not offer it). If the claim was present but unmatched, check that Conditional Access requires MFA for this application and that the accepted values include mfa.

I confirmed a change by signing in again through the identity provider, and it was not saved. On this page the round trip keeps what you entered: you return to the connection form, the save completes, and the card says "Connection saved." (or "Connection saved. Run a test to activate it." for a Draft). A change that included a new client secret is the exception, because the secret is never kept between pages: the other fields are restored and the card says "You are signed in again. Enter the client secret once more and select Save connection." Do that, and the save goes through without another confirmation.

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