Outcome
By the end of this lesson, you will be able to classify an SSO failure into one of four root-cause categories, apply the right fix from each category, and know when to escalate to ZopNight support, and with what details.
| Prerequisites | M4.2.L1-L3 (SSO methods configured) |
| Time | 8 minutes |
1. Concept
Sign-on failures feel chaotic while they are happening. Somebody says they cannot log in, the screenshot shows nothing useful, and each system blames the other.
In practice, almost all of them are one of four things, and each has its own symptom and its own fix.
Work out which one first, then fix it. Doing it the other way round is what turns five minutes into half an hour.
A note on the error text below: ZopNight does not validate SAML itself. The identity provider and ZopNight’s external sign-in service do, so the quoted symptoms are typical wording from the identity provider or sign-in service, not guaranteed. ZopNight’s own login page shows only a few generic messages, such as “Sign-in failed. SAML response was missing.”, “Sign-in failed. The response was too large.” and “Sign-in failed due to an unexpected error.” Treat the IdP’s sign-in logs as the place to find the specific reason.
CATEGORY TYPICAL SYMPTOM OWNER──────────────────────────────────────────────────────────────────────1. Certificate "Invalid signature" / "Cert expired" IdP-side (or stored cert stale)
2. Metadata drift "Audience mismatch" / "Entity ID" Config-side errors (either side)
3. Clock / timing "Assertion expired" soon after issue Both sides (NTP sync)
4. User-side "User not found" / wrong role / Attribute wrong team mappingThe diagnostic flow is: get the exact error and time from the user, identify the category, apply the fix. If two cycles do not resolve, escalate.
Category 1: Certificate issues
Cert issues are the most common SAML failure mode after the initial setup is complete and stable. The cert worked for months, then suddenly does not.
SYMPTOM ROOT CAUSE FIX──────────────────────────────────────────────────────────────────────"Invalid SAML signature" IdP's signing cert does not Send ZopDev the new match the cert ZopNight stored. cert thumbprint so the Often after IdP cert rotation. config is updated.
"Certificate expired" IdP cert has passed its expiry Generate new cert at date. IdP; send ZopDev the new thumbprint; renew the calendar reminder.The cert-expiry case is preventable, but not by ZopNight: the SAML config stores only a cert thumbprint, not an expiry date, so nothing in ZopNight warns you. Put the renewal date in your own calendar 90 days ahead; that gives time to generate the new cert, send ZopDev the new thumbprint, and test without pressure.
Category 2: Metadata drift
Drift happens when the IdP-side config changes (often during routine maintenance) and ZopNight’s stored copy gets out of date.
SYMPTOM ROOT CAUSE FIX──────────────────────────────────────────────────────────────────────"Metadata mismatch" / "Audience IdP changed entity ID, ACS URL, Put the IdP values backmismatch" or other metadata fields. to what ZopDev gave you, or send ZopDev the new metadata URL.
"User attribute missing" IdP claim config changed Re-check the IdP's claim (email no longer sent, or sent config so email is sent with different claim name). again.
"Domain mismatch" User signed in from a domain Either ask ZopDev to add with no matching SAML config. a SAML config for that domain, or have the user sign in with Google or GitHub instead.A simple practice: when an IdP admin changes anything in the IdP-side SAML app, re-test the ZopNight flow within the same change window. Catches drift immediately rather than days later when a user reports the issue.
Category 3: Clock + timing
SAML assertions are valid only for a short window, as protection against replay. If the IdP’s clock drifts too far from the sign-in service’s clock, every assertion is “expired on arrival.” The exact tolerance is set by the sign-in service, not by ZopNight, so do not rely on a specific figure.
SYMPTOM ROOT CAUSE FIX──────────────────────────────────────────────────────────────────────"Assertion expired" soon Clock skew between the IdP and Verify NTP is configuredafter assertion issue the sign-in service exceeds the and syncing on the IdP. service's tolerance. Cloud-hosted IdPs rarely have this issue; self-hosted IdPs do.For OAuth, timing issues are less common because OAuth uses ephemeral codes (single-use, short-lived) rather than time-bound assertions.
Category 4: User-side issues
The user authenticated correctly but ZopNight cannot provision or route the user properly.
SYMPTOM ROOT CAUSE FIX──────────────────────────────────────────────────────────────────────"Lands in onboarding" User signed in but is not a An Admin adds their email member of your org, so they in Settings → Organization have no organisation yet. with a role.
"Role missing" Member was added with "No Assign a role in Settings role", or the role assignment → Organization. Roles never failed. come from the IdP.
"Sees nothing" / "wrong team" Member is not in the expected Add them to the team on the team, or the team owns nothing. Teams page. Teams never come from IdP groups.The wrong-team case is the subtlest. The user authenticates, lands on a Inventory page, and sees nothing: because their team scope is empty (M4.1 L5 covered this state). The fix is team membership on the Teams page; ZopNight does not read IdP groups, so add team membership to your onboarding checklist.
The diagnostic process
1. COLLECT the failure details from the user - The exact error text shown - The time of the attempt and their email Sign-in runs in ZopNight's external auth service before the user reaches your org, so failed sign-ins are not in your org's audit log.
2. CROSS-REFERENCE with IdP-side logs Most IdPs (Okta, Azure AD) log each SAML assertion issuance. Match by timestamp and user. If the IdP issued the assertion but sign-in still failed: ZopNight-side config issue (cert, metadata, clock). If the IdP did not issue: IdP-side issue (config, user state, IdP outage).
3. CLASSIFY into one of the four categories above
4. APPLY the fix
5. RETEST the user's login If success: done. If still failing: re-classify (you might have guessed the wrong category) or escalate.When to escalate
IF you have: - Verified cert + metadata correct - Confirmed clocks are synced - Mapped user attributes correctly - Domain config matches AND still failing:
THEN contact ZopNight support with: - Approximate timestamp of the failure - The user's email and the SSO method attempted - Screenshot of any error message
ZopNight support can read the auth service's own logs, which holddetails you cannot see: assertion contents and low-level SAMLparsing errors.A precise timestamp and email are the key. Without them, support has to search across logs broadly, which is slow and ambiguous.
2. Demo
A real-feeling diagnosis flow:
USER REPORT: "I get 'Invalid signature' when I try to SSO."
STEP 1: Ask Jane for the exact error and time → jane@example.com, 10:42 UTC → Okta sign-in log: assertion issued; Jane saw a signature error (wording varies by IdP) → Category: 1 (Certificate)
STEP 2: Open Okta admin → SAML app for ZopNight → Certificates → Cert status: EXPIRED 3 days ago → Cert was scheduled to renew 7 days ago but the renewal ticket was missed
STEP 3: ROOT CAUSE confirmed: the old cert expired and Okta now signs with the new cert, but ZopNight's SAML config still holds the old one. Signature does not match.
FIX: - In Okta: confirm new cert is active (it is) - Send ZopDev the new cert thumbprint (or the metadata URL) so the SAML config for example.com is updated - Test login: SUCCESS
LEARNING: - Add cert renewal calendar reminder (90 days before next expiry) - Document the renewal process in the team runbook - Confirm Okta's auto-renewal is configured (or set a manual reminder on the IdP side too)
ELAPSED: most of it waiting on the SAML config update.3. Hands-on (5 min)
Audit your SAML cert(s) for expiry:
SAML CONFIGURATION: __________ (domain)CERT EXPIRY DATE: __________DAYS REMAINING: __________
IF <60 days: Schedule renewal in IdP Date: __________ Update calendar with reminder at 90/30/7 days Done: yes / no Plan a test sign-in immediately after rotation Done: yes / no
IF you have multiple SAML configs: Domain 1: __________ Expires: __________ Domain 2: __________ Expires: __________ Domain 3: __________ Expires: __________If you do not have SSO yet, sketch the response runbook for a future “Invalid signature” report: what to ask the user, which IdP page, which fix.
4. Knowledge check
Q1
A user reports “Invalid signature” error on SAML sign-in. Most likely cause:
A. The user typed the wrong password (SAML credentials are not their fault)
B. User is not provisioned
C. The IdP signing cert does not match what ZopNight has stored
D. Cloud outage
Show answer
Correct: C. Common causes: cert expired and was rotated, or IdP-side cert rotation did not propagate. Fix by sending ZopDev the new cert thumbprint. Signature failures are always cert-side, not credential-side. The fix is to align ZopNight’s stored cert with whatever the IdP is currently signing with.
Q2
Assertions are rejected as “expired” within seconds of issue. Most likely cause:
A. A real expiry, since the user simply took too long to complete the sign-in
B. A bug in the assertion parser somewhere in the ZopNight gateway code
C. Network latency between the identity provider and the ZopNight gateway
D. Clock skew between the identity provider and the sign-in service
Show answer
Correct: D. Verify NTP is syncing on both sides; for self-hosted IdPs this is a real risk. Clock skew is the textbook cause of “assertion expired” errors. SAML assertions are valid only briefly, so the clocks must stay synced.
Q3
A user from jane@partner.com cannot log in. ZopNight has a SAML config for example.com only. The right diagnosis:
A. Domain mismatch: no SAML config exists for partner.com
B. The identity provider’s certificate has expired
C. Their assertion failed the signature validation check
D. The identity provider’s clock has drifted out of sync
Show answer
Correct: A. Either ask ZopDev to add a SAML config for that domain (if the partner has their own IdP), or have the user sign in with Google or GitHub instead and be added as a member. Domain mismatch is a routing issue. SAML configs are per-domain; users from other domains have no path through SAML. OAuth or per-domain SAML are the two options.
5. Apply
Start from the user’s exact error text and time, then your IdP’s sign-in logs. Failed sign-ins do not appear in the Audit Logs page, so include the time and email when filing support tickets.
Maintain a small runbook of common SSO failures and their fixes in your team’s wiki: this is the highest-leverage IT/ops document a customer can have.
Related lessons
- L1: Pick your SSO
- L2: SAML per-email-domain
- L3: Google + GitHub OAuth
- T4.M4.3.L1: Audit log: what gets recorded
Module quiz
Complete M4.2 → 10-question module quiz.