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 |
1---2name: sso-saml-troubleshooting3description: 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.4---56# SAML SSO Troubleshooting78SAML SSO into Salesforce fails for a small number of well-known9reasons. The hard part is identifying *which* of the well-known10reasons applies to the specific failure. This skill walks the11diagnostic loop: capture the SAML response, validate it against12Salesforce's expectations, fix at the IdP or SP, retry.1314## Required prerequisites1516- **My Domain is enabled** and deployed for SSO use. Salesforce17 routes SAML through the My Domain hostname; without it, SSO18 cannot work.19- **Salesforce SAML SSO Settings exist** for the relevant IdP20 (Setup -> Single Sign-On Settings).21- **The IdP knows Salesforce as a Service Provider** with the22 Salesforce-side Entity Id (typically `https://saml.salesforce.com`23 for SP-initiated, or the My Domain URL).2425## The diagnostic loop2627```28Symptom -> Capture SAML Response -> Identify failing check -> Fix -> Retry29```3031The SAML Assertion Validator (Setup -> Single Sign-On Settings ->32SAML Assertion Validator) accepts a base64-encoded SAML response and33runs Salesforce's exact checks against it, returning a per-check34pass / fail. This is the fastest way to narrow the problem.3536The Login History (Setup -> Login History) records every login37attempt, including SAML failures, with a Status field that names38the failing check (e.g. "Signature Failure", "Audience Mismatch",39"Assertion Expired").4041## The well-known failure modes4243| Symptom / Error | Cause | Fix |44|---|---|---|45| "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 |46| "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) |47| "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 |48| "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 |49| "Assertion Not Yet Valid" / "NotBefore in future" | IdP clock ahead of Salesforce | Fix IdP clock |50| "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 |51| "Federation Id is not unique" | Two users share the same Federation Id | Deduplicate Federation Ids on the user record |52| 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 |5354## IdP-initiated vs SP-initiated5556- **IdP-initiated.** User starts at the IdP (e.g. Okta dashboard),57 clicks the Salesforce app tile; the IdP POSTs a SAML response to58 Salesforce. Salesforce expects an `InResponseTo` of empty for this59 flow.60- **SP-initiated.** User starts at the Salesforce login page, gets61 redirected to the IdP via SAMLRequest, IdP responds. Salesforce62 expects `InResponseTo` matching the request it sent.6364A common bug: misconfigured IdP-initiated when the user expects65SP-initiated, or vice versa. The error appears as `InResponseTo`66mismatch.6768## Recommended Workflow69701. **Reproduce and capture.** Use a browser SAML tracer extension to capture the encoded SAML response from a failed login. Decode it (base64) for inspection.712. **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.723. **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).734. **Identify the check.** Match the failing check to the well-known table above.745. **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).756. **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.767. **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.7778## What This Skill Does Not Cover7980| Topic | See instead |81|---|---|82| Setting up SAML SSO from scratch | `security/sso-saml-setup` |83| OAuth / OpenID Connect SSO | `security/oauth-openid-troubleshooting` |84| MFA / multi-factor configuration | `security/mfa-configuration` |85| External Identity / Customer SSO | `security/customer-sso-experience-cloud` |
PranavNagrecha