how to troubleshoot SSO login failures for users

TL;DR

SSO failures are a three-way handshake between the user, your app, and their identity provider, and the error almost always lives on the provider side. Read the actual error text instead of guessing, check the email-domain match first, and learn the sentence that hands the ticket to their IT admin cleanly. Half your job here is knowing what is not yours to fix.

The query

how to troubleshoot SSO login failures for users

Use this when

• The "Sign in with" button errors or loops
• SAML or OIDC login fails after the redirect
• Only some users at a company are affected
• A new employee cannot SSO but older ones can
• IT asks you what to check on their side

Not for

• Username and password logins
• Account lockouts from failed attempts
• Setting up a brand-new SSO connection for a customer
• API keys or service accounts

Steps

1. Capture the exact error and where it appears

Ask the user to copy the error text word for word, and note whether it appears on your login page, on the provider's page, or after being bounced back. Provider-page errors are provider problems. Your-page errors are yours.

Expected output: the error text and which side of the redirect showed it.

2. Check the email address matches the SSO domain

The most common failure: the user types a personal or alias address while the SSO connection expects the company domain. Confirm the email they entered matches the domain tied to the SSO setup, including any subdomain.

Expected output: domain match confirmed, or the user redirected to the right address.

3. Rule out a stale session on the provider side

Have them sign out of the identity provider completely, or try the login in an incognito window. A half-expired session at the provider causes silent loops where the user bounces between the two sites forever.

Expected output: the loop breaks, or the provider session is ruled out.

4. Check whether the user is actually assigned the app

In most providers, an admin must grant each user access to your app. New hires fail SSO constantly because nobody assigned them. If older employees work and the new one does not, this is the answer, and only their IT admin can fix it.

Expected output: a yes-or-no on app assignment, from their admin.

5. Hand off to their IT with the right details

Give their admin the timestamp, the user's email, and the exact error. Say plainly what you checked on your side so they do not start over. If your logs show the provider never sent a response, say so, because that proves the break is upstream.

Expected output: a ticket their IT can act on without asking you for basics.

Ready-to-use handoff message

I've checked our side: the login attempt reached us at [time]
but your identity provider didn't send back a completed login
for [their email].

What usually fixes this on the company side:
1. Confirm [their email] is assigned to our app in your
   provider's admin panel
2. Check the app's user list includes any new hires

Once that's confirmed, have them try in an incognito window.
If it still fails, send me the exact error text and I'll dig
deeper on our end.

Variant phrasings

sign in with google not working support

Steps 1 through 3. Google-side errors usually mean the wrong Google account is active in the browser, especially with multiple profiles.

SAML login loop troubleshooting

Steps 1 and 3. Loops are almost always a stale provider session or a clock skew between the provider and your servers.

new employee cannot log in with SSO

Step 4 first. It is the app assignment, every time, until proven otherwise.

Why it happens

SSO outsources the "who is this person" question to the customer's provider, which means your login page is now dependent on a system you cannot see into. Any mismatch, expired assignment, stale session, or config drift on their side surfaces as your login being broken. The user blames your app because your logo is on the button, but the fix usually lives in their admin console.

Edge cases

• User has two accounts with similar emails: the provider may be sending the personal one while your app expects the work one. Check the email in your user record against what they typed.
• SSO worked until the company changed providers: the connection on your side may still point at the old one. This is a reconfiguration, not a user bug. Escalate.
• Intermittent failures for everyone: look at your own side. Provider outages and expired certificates on your end hit all users at once.
• The error says the user does not exist in your app: they may need an account created first before SSO can link. Check whether your setup auto-provisions or needs manual invites.
• IT insists everything is fine on their side: ask for a screenshot of the user's app assignment and a fresh timestamped attempt. "Fine" without evidence is not a diagnosis.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_MD2FXfjpVRytIw0tzfTRYA