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."4category: security5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Security8 - Reliability9triggers:10 - "saml sso not working salesforce error login"11 - "saml assertion validator setup login history"12 - "nameid format mismatch idp salesforce"13 - "saml signing certificate expired entity id"14 - "idp initiated vs sp initiated saml relay state"15 - "saml clock skew not before not after"16 - "my domain saml sso prerequisite"17tags:18 - saml19 - sso20 - troubleshooting21 - idp22 - my-domain23inputs:24 - "Symptom (login error message, redirect loop, success-but-no-access)"25 - "Whether IdP-initiated or SP-initiated flow is in use"26 - "Sample SAML Response captured at the browser (encoded or decoded)"27outputs:28 - "Identified failing check (audience / signature / NameID / clock)"29 - "Specific configuration fix on the IdP or SP side"30 - "Validation steps using SAML Assertion Validator and Login History"31dependencies: []32version: 1.0.033author: Pranav Nagrecha34updated: 2026-05-0535metadata:36 source: https://skillmd.com/skills/pranavnagrecha/sso-saml-troubleshooting37---3839# SAML SSO Troubleshooting4041SAML SSO into Salesforce fails for a small number of well-known42reasons. The hard part is identifying *which* of the well-known43reasons applies to the specific failure. This skill walks the44diagnostic loop: capture the SAML response, validate it against45Salesforce's expectations, fix at the IdP or SP, retry.4647## Required prerequisites4849- **My Domain is enabled** and deployed for SSO use. Salesforce50 routes SAML through the My Domain hostname; without it, SSO51 cannot work.52- **Salesforce SAML SSO Settings exist** for the relevant IdP53 (Setup -> Single Sign-On Settings).54- **The IdP knows Salesforce as a Service Provider** with the55 Salesforce-side Entity Id (typically `https://saml.salesforce.com`56 for SP-initiated, or the My Domain URL).5758## The diagnostic loop5960```61Symptom -> Capture SAML Response -> Identify failing check -> Fix -> Retry62```6364The SAML Assertion Validator (Setup -> Single Sign-On Settings ->65SAML Assertion Validator) accepts a base64-encoded SAML response and66runs Salesforce's exact checks against it, returning a per-check67pass / fail. This is the fastest way to narrow the problem.6869The Login History (Setup -> Login History) records every login70attempt, including SAML failures, with a Status field that names71the failing check (e.g. "Signature Failure", "Audience Mismatch",72"Assertion Expired").7374## The well-known failure modes7576| Symptom / Error | Cause | Fix |77|---|---|---|78| "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 |79| "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) |80| "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 |81| "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 |82| "Assertion Not Yet Valid" / "NotBefore in future" | IdP clock ahead of Salesforce | Fix IdP clock |83| "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 |84| "Federation Id is not unique" | Two users share the same Federation Id | Deduplicate Federation Ids on the user record |85| 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 |8687## IdP-initiated vs SP-initiated8889- **IdP-initiated.** User starts at the IdP (e.g. Okta dashboard),90 clicks the Salesforce app tile; the IdP POSTs a SAML response to91 Salesforce. Salesforce expects an `InResponseTo` of empty for this92 flow.93- **SP-initiated.** User starts at the Salesforce login page, gets94 redirected to the IdP via SAMLRequest, IdP responds. Salesforce95 expects `InResponseTo` matching the request it sent.9697A common bug: misconfigured IdP-initiated when the user expects98SP-initiated, or vice versa. The error appears as `InResponseTo`99mismatch.100101## Recommended Workflow1021031. **Reproduce and capture.** Use a browser SAML tracer extension to capture the encoded SAML response from a failed login. Decode it (base64) for inspection.1042. **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.1053. **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).1064. **Identify the check.** Match the failing check to the well-known table above.1075. **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).1086. **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.1097. **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.110111## What This Skill Does Not Cover112113| Topic | See instead |114|---|---|115| Setting up SAML SSO from scratch | `security/sso-saml-setup` |116| OAuth / OpenID Connect SSO | `security/oauth-openid-troubleshooting` |117| MFA / multi-factor configuration | `security/mfa-configuration` |118| External Identity / Customer SSO | `security/customer-sso-experience-cloud` |