Practice: The SSO and integration troubleshooting runbook
Generated by Claude (Fable 5.1) by hand from the identity and integration ops spike, Scout learning center on 2026-10-14.
Main tool: SAML-tracer, HAR files and the decoders, with Keycloak's logs · A runbook is learned by producing each failure on purpose where you can see both sides, and the local Keycloak and node-saml setup from the earlier paths lets you break the audience, the ACS, the clock, the secret, the code and the scope one at a time while capturing with the tools a customer call allows (a tracer, a HAR, a log). The error rows that came from the learning center's runs are verbatim; the vendor rows are from the official references. · Alternatives: Burp Suite with the SAML Raider extension edits and replays SAML messages for deeper testing; jwt_tool and the step CLI decode and test tokens from the shell; a customer's sandbox tenant with its sign-in logs is the best place to see the vendor side; the Entra test-SSO page and Okta's system log need an account the learning center did not create.
Every step links into the tool's own documentation; links were checked on 2026-10-14 · version 1
Setup (one time)
1. Have the SAML practice path's Keycloak IdP and node-saml SP running, and the OpenID Connect path's public client configured; install the SAML-tracer extension in Firefox or Chrome.
The runbook is practised by breaking a working setup; both flows have to work first.
Explained in: SAML-tracer (Firefox add-on) (addons.mozilla.org), checked 2026-10-14
Done when: A SAML login and an OIDC login both succeed in the browser and the tracer icon shows messages when you log in.
2. Keep three things open: the browser's Network tab (with 'preserve log' on), the SAML lesson's two-line decoder (or samltool.com for local messages only), and the JWT decode one-liner from the token lesson.
Capture and decode are the first two steps of every call; having the tools ready is the preparation.
Explained in: OneLogin SAML tools: decode SAML messages (www.samltool.com), checked 2026-10-14
Done when: You can decode a SAMLRequest, a SAMLResponse and a JWT from a capture in under a minute each.
Steps
1. With the tracer recording, run the SAML login; export the trace; identify the AuthnRequest and the Response and read, from the trace, the Destination, the AssertionConsumerServiceURL, the Issuer, the Audience, the NameID and the signature elements.
The tracer is the first tool on any SSO ticket; reading a good trace once makes the bad ones legible.
Explained in: SAML-tracer (Firefox add-on) (addons.mozilla.org), checked 2026-10-14
Done when: Your export is saved and you can point at each of the six values in it.
2. With the Network tab recording, run the OIDC login and save the HAR; run the HAR-reading script from the lesson and find the redirect that carries the code and state, and the token request that follows.
A HAR is what a customer can send you without any extension; knowing where the flow is in it is the skill.
Explained in: Chrome DevTools: Network features reference (developer.chrome.com), checked 2026-10-14
Done when: The script prints the redirect chain with the callback Location containing code and state, and you can say which entries would be sensitive in a customer's HAR.
3. Paste the local SAMLResponse (never a customer's) into the samltool.com decoder, and inflate the SAMLRequest from the redirect with the Python two-liner; compare the two results with the tracer's.
The decoders are interchangeable; the rule about customer data is not.
Explained in: OneLogin SAML tools: decode SAML messages (www.samltool.com), checked 2026-10-14
Done when: All three decodings agree, and you know which tool you would use with no extension and no script available.
4. Break the SP's audience (set it to a different string), log in, and read the exact error from the SP; restore it.
Audience mismatch is the most common SAML failure after certificates; the error text is a runbook row.
Explained in: Microsoft Entra: Debug SAML-based single sign-on to applications (learn.microsoft.com), checked 2026-10-14
Done when: The SP rejects with an audience error text you have recorded verbatim, and the tracer shows the Audience in the assertion unchanged.
5. Break the ACS: change the SP's callback URL to a path Keycloak does not have registered, log in, and read the error on the IdP's page and in its log; restore it.
ACS and redirect URI mismatches fail on the IdP side before the SP sees anything; knowing which side errs is half the diagnosis.
Explained in: Keycloak: Configuring logging (www.keycloak.org), checked 2026-10-14
Done when: Keycloak refuses the AuthnRequest with an invalid-request error naming the ACS or redirect, and the row is recorded.
6. Set the SP's accepted clock skew to 0 and shift the SP's idea of time by a few minutes (or wait for an assertion to age past NotOnOrAfter), log in, and read the error; restore the skew.
Clock errors look random to users ('works on one node'); seeing the exact text once makes them recognisable.
Explained in: Microsoft Entra: Debug SAML-based single sign-on to applications (learn.microsoft.com), checked 2026-10-14
Done when: The SP rejects with a 'not yet valid' or 'expired' style error, and you can state what skew a production SP should accept.
7. Produce the OIDC failures on purpose: a token request with a wrong client secret, a replayed authorization code, a request with an unregistered redirect_uri, and a userinfo call with a token lacking the openid scope. Record error and error_description from each response body.
The RFC's error codes have exact meanings; a table of them with real text stops the guessing on a call.
Explained in: RFC 6749 section 5.2: Error Response (datatracker.ietf.org), checked 2026-10-14
Done when: Four rows: 401 unauthorized_client or invalid_client, 400 invalid_grant, the IdP's redirect_uri error page, and 403 from userinfo; all with the verbatim text.
8. Raise Keycloak's log level for the SAML and OIDC protocol categories and the events category, repeat two of the failures, and find each in the container log.
The IdP's log is the vendor-side evidence; a local IdP is the only one whose log you can read in full.
Explained in: Keycloak: Configuring logging (www.keycloak.org), checked 2026-10-14
Done when: The log shows a line for each rejection with the reason, and you can say which category produced it.
9. Read the Entra SAML debugging page and the error codes reference, and (needs a free account; not run by the learning center) run 'Test single sign-on' on an enterprise application to download the SAML request and read the resolution guidance; read Okta's error codes reference and find E0000004 and E0000011.
Customers paste these codes into tickets; recognising them saves the first round trip.
Explained in: Microsoft Entra: authentication and authorization error codes (learn.microsoft.com), checked 2026-10-14
Done when: You can describe what the Entra test button does and name three AADSTS codes and two Okta codes with their causes.
10. Build the runbook table with at least ten rows from the steps above and the lesson's lists: symptom, exact error text, cause, fix, which capture showed it. Add the three SFTP and webhook rows from the machine-to-machine and file feed lessons.
The table is the runbook; every incident after this adds a row.
Explained in: Postman: Troubleshoot API requests (learning.postman.com), checked 2026-10-14
Done when: The table has ten or more rows with verbatim error text in each, and a colleague could use it on a call without you.