SSO Troubleshooting Tracer
Status
Design and Prototype
Maturity
Browser extension concept with documented flow
Evidence
Flow documentation complete · Sanitized trace report added · Repo pending
Next
Build Chrome extension MVP
Architecture
Problem Statement
SSO failures are opaque by design — assertions are base64-encoded, tokens are JWT-encoded, and error messages from service providers are deliberately vague. Enterprise support teams spend significant time diagnosing federation failures that could be resolved in minutes with the right tooling. MTTR for SSO outages is disproportionately high relative to the underlying complexity of most failures.
What Was Built
A structured SSO troubleshooting workflow with a documented failure pattern library covering SAML 2.0 and OIDC. The design targets a browser extension that captures SSO traffic, decodes payloads, redacts sensitive fields, and maps observed symptoms to known failure patterns with resolution steps.
The current artefact is the documented workflow and failure pattern library. The browser extension implementation is the next milestone.
Supported Protocols
SAML 2.0
- · POST binding trace and decode
- · Assertion structure inspection
- · Signature and certificate validation
- · Attribute mapping verification
- · Conditions: NotBefore, NotOnOrAfter, AudienceRestriction
OIDC / OAuth 2.0
- · Authorization code flow analysis
- · PKCE: code_challenge and code_verifier verification
- · Token exchange inspection
- · Redirect URI validation
- · Cookie and session state analysis
SSO Failure Pattern Library
| Failure Pattern | Protocol | Symptom | Detection | Resolution |
|---|---|---|---|---|
| Clock skew | SAML | NotBefore/NotOnOrAfter rejected | Compare IdP and SP system times | Sync NTP; allow 5-min skew |
| Wrong ACS URL | SAML | SP rejects assertion destination | Compare Destination vs SP ACS URL | Correct SP metadata or IdP config |
| Expired signing cert | SAML | Signature validation failure | Check IdP cert expiry vs SP metadata | Renew cert, update SP metadata |
| Missing attribute | SAML | SP returns access denied | Inspect assertion attributes | Add attribute mapping in IdP |
| Missing PKCE verifier | OIDC | Token endpoint returns invalid_grant | Check code_verifier and hash | Implement PKCE correctly |
| SameSite cookie issue | OIDC | Session cookie not set after redirect | Inspect Set-Cookie headers | Set SameSite=None; Secure |
| Wrong redirect URI | OIDC | Auth server returns invalid_request | Compare registered vs actual redirect_uri | Register correct URI in IdP |
SSO Trace Report — Sanitized Demo View
⚠Sanitized demo view — production data redacted. Illustrative trace based on the documented failure patterns above.
Session ID
sess-[redacted]
Protocol
SAML 2.0
IdP
idp.[redacted].com
SP
sp.[redacted].com
Trace steps
- 09:14:22Z→ AuthnRequest sent to idp.[redacted].com
- 09:14:23Z→ IdP authentication successful
- 09:14:24Z→ SAMLResponse POST to sp.[redacted].com/acs
- 09:14:24Z✗ Assertion rejected — NotBefore condition failed
NotOnOrAfter="2026-05-17T09:21:00Z">
<!-- SP clock: 2026-05-17T09:13:45Z — 136s behind IdP -->
Detected failure: Clock Skew
SP system clock is 136 seconds behind IdP. NotBefore condition fails SP-side validation.
Resolution
Sync SP NTP. Allow 5-minute clock skew tolerance in SP SAML configuration (standard: 300 s).
Employer Value
Risk reduced
Prolonged SSO outages due to opaque failure diagnosis
Operational value
Structured diagnostics reduce MTTR for federation issues
IAM domain
SAML 2.0, OIDC, federation troubleshooting
Seniority signal
Tooling design for enterprise support — not just protocol knowledge
Evidence Roadmap
The following evidence items are planned or in progress. Documentation and architecture content is complete; screenshots, repos, and demos will be added as the project matures.
Failure pattern library
[ Documented above ]
SSO Trace Report
[ Sanitized trace report added ]
Browser extension prototype
[ Repo pending ]
Demo video
[ Demo video pending ]
SAML decode walkthrough
[ Screenshot pending ]