Home / security / sso-saml-troubleshooting

sso-saml-troubleshooting

Troubleshoot SAML SSO failures — assertion errors, certificate mismatch, JIT provisioning. Triggers: SAML error, SSO login failure, assertion invalid. NOT for initial SSO configuration - use security/sso-configuration.

v1.0.0
Salesforce Spring '25+
Updated 2026-05-05
Security
Reliability

saml
sso
troubleshooting
idp
my-domain

Open the skill folder on GitHub

SAML SSO Troubleshooting

SAML SSO into Salesforce fails for a small number of well-known reasons. The hard part is identifying which of the well-known reasons applies to the specific failure. This skill walks the diagnostic loop: capture the SAML response, validate it against Salesforce's expectations, fix at the IdP or SP, retry.

Required prerequisites

My Domain is enabled and deployed for SSO use. Salesforce
routes SAML through the My Domain hostname; without it, SSO cannot work.
Salesforce SAML SSO Settings exist for the relevant IdP
(Setup -> Single Sign-On Settings).
The IdP knows Salesforce as a Service Provider with the
Salesforce-side Entity Id (typically https://saml.salesforce.com for SP-initiated, or the My Domain URL).

The diagnostic loop

Symptom -> Capture SAML Response -> Identify failing check -> Fix -> Retry

The SAML Assertion Validator (Setup -> Single Sign-On Settings -> SAML Assertion Validator) accepts a base64-encoded SAML response and runs Salesforce's exact checks against it, returning a per-check pass / fail. This is the fastest way to narrow the problem.

The Login History (Setup -> Login History) records every login attempt, including SAML failures, with a Status field that names the failing check (e.g. "Signature Failure", "Audience Mismatch", "Assertion Expired").

The well-known failure modes

Symptom / Error	Cause	Fix
"Signature Failure"	IdP's signing cert in Salesforce SSO Settings does not match the cert that signed the response	Re-upload the IdP's current public signing cert into the SSO Settings
"Audience Mismatch"	`<Audience>` element in the assertion does not match Salesforce's expected EntityId	Set IdP audience to `https://saml.salesforce.com` (or My Domain URL, depending on flow)
"Issuer Mismatch"	`Issuer` in the response does not match the Issuer configured in SSO Settings	Update SSO Settings Issuer to match the IdP's exact issuer string
"Assertion Expired" / "NotOnOrAfter in past"	Clock skew between IdP and Salesforce, or assertion expiry too short	Fix IdP clock; if drift is unavoidable, increase IdP's NotOnOrAfter window
"Assertion Not Yet Valid" / "NotBefore in future"	IdP clock ahead of Salesforce	Fix IdP clock
"User does not exist"	NameID does not match a Salesforce user (by Federation ID, Username, or Email — depending on SSO Settings)	Either provision the user in Salesforce or change SSO Settings to match the IdP's NameID format
"Federation Id is not unique"	Two users share the same Federation Id	Deduplicate Federation Ids on the user record
Login redirects but lands on user's home with a "session expired" feel	RelayState handling broken	Inspect the `RelayState` parameter; Salesforce uses it to redirect post-login

IdP-initiated vs SP-initiated

IdP-initiated. User starts at the IdP (e.g. Okta dashboard),
clicks the Salesforce app tile; the IdP POSTs a SAML response to Salesforce. Salesforce expects an InResponseTo of empty for this flow.
SP-initiated. User starts at the Salesforce login page, gets
redirected to the IdP via SAMLRequest, IdP responds. Salesforce expects InResponseTo matching the request it sent.

A common bug: misconfigured IdP-initiated when the user expects SP-initiated, or vice versa. The error appears as InResponseTo mismatch.

Recommended Workflow

Reproduce and capture. Use a browser SAML tracer extension to capture the encoded SAML response from a failed login. Decode it (base64) for inspection.
Run the SAML Assertion Validator. Setup -> Single Sign-On Settings -> select the IdP -> SAML Assertion Validator. Paste the encoded response. The output names the failing check.
Cross-check Login History. Setup -> Login History. Find the failed attempt; the Status column names the failing check from the platform side (sometimes more specific than the validator).
Identify the check. Match the failing check to the well-known table above.
Fix at the right end. Most fixes are IdP-side (cert rotation, audience update, clock fix). Some are SP-side (Salesforce SSO Settings: Issuer, Identity Provider Login URL, NameID format, Federation Id mapping).
Re-test with a fresh login. Browser caches and IdP session caches can mask fixes; force a fresh login with cleared cookies or in an incognito window.
Document the runbook. Cert rotation will happen again. Capture the IdP cert refresh process, the Salesforce SSO Settings step, and a test plan in the runbook.

What This Skill Does Not Cover

Topic	See instead
Setting up SAML SSO from scratch	`security/sso-saml-setup`
OAuth / OpenID Connect SSO	`security/oauth-openid-troubleshooting`
MFA / multi-factor configuration	`security/mfa-configuration`
External Identity / Customer SSO	`security/customer-sso-experience-cloud`