Troubleshooting single sign-on

This article is a triage guide for SSO problems, from the wizard refusing to validate, to a member who can't sign in, to a full IdP outage. It's aimed at the organisation owner (the only role that can see SSO config). If you're a member who can't sign in, see Signing in with single sign-on first.

Pick your symptom

Discovery URL failures

When you click Validate connection on the wizard, GarageHQ fetches the discovery URL you gave it (.../.well-known/openid-configuration) and pulls the issuer, the authorisation endpoint, and the JWKS URL out of it. If that fetch fails, you'll see one of these in the wizard:

• Discovery URL is not reachable, typo in the URL, the hostname doesn't resolve, or the IdP is returning a non-200. Open the URL in your browser. If you don't see a JSON document, the URL is wrong.
• Discovery URL responded but the JSON didn't include the expected fields, the URL points at something OIDC-shaped but isn't a full OIDC discovery document. For Entra ID, double-check the /v2.0/ segment is in the URL (without it, Entra serves a v1 document that GarageHQ can't read).
• Issuer mismatch, the discovery doc's issuer claim doesn't match the URL. Almost always the /v2.0/ issue on Entra, but Auth0 can sometimes return a different issuer for custom domains.

For each one, the fix is to correct the discovery URL in the wizard and re-validate.

Domain verification failures

After you add a domain (for example acme.co.uk) on the Verified domains card, you have to publish a TXT record on that domain's DNS before GarageHQ trusts it. The wizard tells you exactly what to publish:

Host:    _garagehq-sso.acme.co.uk
Type:    TXT
Value:   garagehq-sso=<your token>

Common failure causes:

• Record is on the apex (acme.co.uk) rather than the _garagehq-sso subdomain. Many DNS UIs auto-append the domain to the host field, so if you typed _garagehq-sso.acme.co.uk you ended up with a record at _garagehq-sso.acme.co.uk.acme.co.uk. Fix: enter _garagehq-sso only.
• Value missing the garagehq-sso= prefix. The full value must start with garagehq-sso= then your token. Just pasting the token alone won't match.
• DNS hasn't propagated yet. Cloudflare DNS is usually under five minutes; some registrars take up to an hour.

You can confirm what GarageHQ sees by querying Cloudflare's resolver directly from your terminal:

dig TXT _garagehq-sso.acme.co.uk @1.1.1.1

If the response doesn't contain garagehq-sso=<token>, the record isn't live where GarageHQ is looking. Wait a bit longer, or check your DNS provider's UI for typos in the host or value.

Test sign-in failures

After you've saved a configuration AND verified at least one domain, the Test sign-in card lights up. Clicking Run test sign-in opens a new tab, redirects to your IdP, and bounces back to /settings/sso?test=success if all is well, or shows the error if not.

The error is recorded in the Recent sign-in events table at the bottom of the SSO settings page, with the message your IdP returned verbatim.

If the error doesn't look like any of the above, check Recent sign-in events for the raw message. The IdP-side reason is usually self-explanatory once you can see it.

Alias vs UPN gotcha

Microsoft Entra often lets you sign in with an alias (you@brand.com), but the ID token it returns contains your canonical email, the UPN, which might be you@tenant.onmicrosoft.com. GarageHQ reads the canonical email from the token.

This means you can sign in successfully at Entra but get Email not on a verified domain at GarageHQ, because you verified brand.com but the token says tenant.onmicrosoft.com.

Fix: verify the UPN's domain, not the alias domain. Open Entra → Users → your account → Account → User principal name to see which domain to verify.

Enforcement gate

Enforce SSO doesn't become available until BOTH of these are true:

• Your wizard state is Testing (set by clicking Start testing in the Enforcement card, only available when you have at least one valid config + one verified domain)
• You've completed at least one successful test sign-in in the last 24 hours

The 24-hour window prevents the case where an old test success masks a config change that broke the IdP round-trip in the interim.

If Enforce SSO is greyed out, look at the reason text next to it, the wizard tells you which precondition is missing.

The NoSso error

A member who used to sign in without issue reports they're being sent to https://app.garagehq.uk/login?error=NoSso. Two causes:

• Wizard state is disabled. You haven't clicked Start testing yet, so even though config exists, SSO routing is off. The member's email matched a verified domain, but there's nowhere to route them.
• The email isn't on a verified domain. The user signed in as (say) their.name@gmail.com, which doesn't match any of your verified domains.

The wizard's State banner at the top of the SSO settings page tells you which one applies. Members can sign in via the regular picker if their email isn't on a verified domain.

Locked-out recovery

The single most important page in this article. If a configuration change has locked out members (or you, as the owner):

1. If you can still get in as owner: open Settings → Single sign-on, click Disable enforcement on the Enforcement card. The change is immediate, no gate, no confirmation. The org flips back to Testing, and members on verified domains regain access via the regular picker straight away.
2. If you've locked yourself out too: sign in with a break-glass account. Any email you nominated under Break-glass accounts retains access to the regular picker even with SSO enforced. From there, disable enforcement.
3. If you didn't configure break-glass: email hello@garagehq.uk with your org name and the email address you usually sign in with. We can disable enforcement server-side, usually within an hour during UK business hours.

Automatic rollback

There's a safety net even if you didn't set up break-glass. If 50 sign-in failures pile up in a 10-minute window, a background job at GarageHQ flips your org back to Testing automatically. The threshold is high enough to ignore the occasional typo, low enough to catch a configuration that's broken for a whole workforce.

You'll see the rollback as an entry in Recent sign-in events marked "Auto-rollback to Testing, failure rate exceeded threshold".

Drift from working state

SSO was set up months ago and worked fine, but it suddenly stopped. A few common causes:

• Client secret rotated at the IdP. Entra secrets expire after their configured lifetime (default 6 months). Generate a new one, paste the value into GarageHQ, save. The cached JWKS doesn't need a refresh, that's keyed off the issuer.
• Domain ownership changed. If your organisation moved to a new email domain and the old domain's TXT record is no longer published, Verify flips that domain back to pending. Members on the old domain can still sign in if the record's been re-published; otherwise re-verify with the new TXT or rotate the verified-domain list.
• IdP added MFA conditional access. If MFA was added between yesterday and today, sign-ins that worked yesterday will now require a second factor. Not a GarageHQ problem, but worth knowing.
• IdP-side disabled the application. Some IdPs auto-disable applications that haven't been used for a long stretch. Open the IdP's app registration and check it's still enabled.

If none of these match, Disable enforcement so the business isn't blocked, then run a Test sign-in. The error in Recent sign-in events usually points at the cause.

When to escalate to us

Email hello@garagehq.uk (or security@garagehq.uk if you suspect an authentication bypass) when:

• You're locked out and don't have a break-glass account
• The IdP error is something this article doesn't cover and you can't reproduce
• You believe a misconfiguration has leaked access (a non-member can sign in)
• You've followed the steps and the Recent sign-in events log shows no entry at all, which means the request never reached GarageHQ, and we need to look at the routing layer

Include the org name, the time window the issue spans, and the email address(es) that can't sign in. We'll usually reply within a working day; emergency lockouts get same-day attention during UK office hours.