n8n SAML SSO error – fix for redirect URI mismatch and attribute mapping

n8n Authentication Errors / Leave a Comment

Step by Step Guide to solve n8n SAML SSO Authentication Error

 

Quick Diagnosis

If SAML‑based SSO to n8n returns “Invalid SAML response” or “Issuer mismatch”, the quickest fix is to:

  1. Make SAML_ENTITY_ID in n8n exactly match the IdP Issuer.
  2. Add the ACS URL (https://<your‑n8n‑host>/auth/saml/callback) as a Valid Assertion Consumer Service in the IdP (POST binding).
  3. Upload the IdP signing certificate to n8n (SAML_CERT) and ensure the IdP signs assertions with that cert.

Restart n8n and retry login – the error disappears in >95 % of cases.

We cover this in detail in the n8n Authentication Errors Guide

(If the problem persists, follow the full checklist below.)

1. Why n8n’s SAML SSO Can Fail

If you encounter any oauth2 redirect uri mismatch resolve them before continuing with the setup.

Symptom Typical Root Cause Where It Shows Up
“Invalid SAML response” Assertion signature cannot be verified n8n logs → SAML response validation failed
“Issuer mismatch” SAML_ENTITY_ID ≠ IdP Issuer n8n logs → Issuer does not match configured entity ID
“AudienceRestriction failed” ACS URL not listed in IdP’s Audience n8n logs → AudienceRestriction validation error
“No SAMLResponse parameter” Browser blocked POST or IdP mis‑configured RelayState Browser dev tools → missing SAMLResponse field
“Certificate expired” IdP signing cert past its validity period n8n logs → Certificate has expired

Understanding the symptom points you to the appropriate section of this guide.

2. Prerequisites – What You Need Before Debugging

If you encounter any ldap bind failure resolve them before continuing with the setup.

Item Why It Matters How to Obtain
n8n version SAML support stabilised in v0.221.0 n8n --version
IdP metadata XML Supplies Entity ID, ACS URLs, certificates Export from Azure AD, Okta, Keycloak, etc.
Access to n8n environment To edit .env or Docker compose SSH / docker exec
Log access Detailed error messages are in n8n.log docker logs <container> or journalctl -u n8n

EEFA note: Never edit a live production .env without a backup. Test changes in a staging environment first; a bad SAML config can lock out all users.

3. Verify the Core SAML Settings

Micro‑summary: Align n8n’s Entity ID, ACS URL, and signing certificate with the IdP metadata.

3.1. Entity ID & Issuer Alignment

# Example snippet from .env
SAML_ENTITY_ID="https://sso.mycompany.com/saml/metadata"
SAML_CERT="/home/n8n/certs/idp_cert.pem"
  1. Open the IdP metadata file (metadata.xml).
  2. Locate <EntityDescriptor entityID="…">.
  3. Ensure the value exactly matches SAML_ENTITY_ID.
  4. If they differ, either update SAML_ENTITY_ID or re‑export the IdP metadata with the correct Entity ID.

3.2. Assertion Consumer Service (ACS) URL

n8n Expected ACS Format
https://<HOST>/auth/saml/callback Must be reachable via HTTPS

* In the IdP console, add this URL to the Assertion Consumer Service (POST) list.
* Confirm POST Binding is selected (not Redirect).

3.3. Signing Certificate Consistency

# Show certificate subject for quick comparison
openssl x509 -in /home/n8n/certs/idp_cert.pem -noout -text | grep "Subject:"

The certificate’s Subject and Serial Number should appear in the IdP metadata under <KeyDescriptor use="signing">.
When the IdP rotates keys, replace SAML_CERT with the new PEM file and restart n8n.

3.4. Enable Verbose SAML Logging (temporary)

Add the following line to .env and restart n8n:

SAML_DEBUG=true

Reproduce the error; the log will now include the raw, Base64‑decoded SAML response, making mismatches easier to spot.

4. Production‑Ready n8n SAML Configuration

Micro‑summary: A minimal, version‑controlled .env snippet for reliable SAML operation.

# Core SAML settings (do NOT commit to VCS)
SAML_ENTITY_ID="https://sso.mycompany.com/saml/metadata"
SAML_ENTRY_POINT="https://sso.mycompany.com/saml/sso"
SAML_CERT="/opt/n8n/certs/idp_cert.pem"

# Optional attribute mapping & hardening
SAML_USERNAME_ATTR="email"
SAML_FIRSTNAME_ATTR="givenName"
SAML_LASTNAME_ATTR="sn"
SAML_FORCE_AUTHN=true
SAML_SIGNATURE_ALGORITHM="sha256"

EEFA tip: Store certificates outside the container (e.g., /opt/n8n/certs) and mount them read‑only to prevent accidental tampering.

5. Debug the Most Common Errors

Micro‑summary: Targeted fixes for each frequent SAML failure.

5.1. “Invalid SAML response”

  1. Signature algorithm mismatch – IdP may use RSA‑SHA256 while n8n defaults to SHA1. Set SAML_SIGNATURE_ALGORITHM="sha256" (see Section 4).
  2. Clock skew – Ensure both IdP and n8n hosts sync via NTP (≤5 min drift).

5.2. “Issuer mismatch”

  1. Double‑check SAML_ENTITY_ID.
  2. Some IdPs expose a friendly name; always use the Entity ID, not the display name.

5.3. “AudienceRestriction failed”

  1. Verify the <Audience> element inside the SAML Assertion equals SAML_ENTITY_ID.
  2. If multiple Audience values are present, the first must match.

5.4. “No SAMLResponse parameter”

  1. Confirm the browser isn’t blocking third‑party cookies or POST data (strict CSP).
  2. Test in an incognito window with a clean profile.

5.5. “Certificate expired”

  1. Replace the PEM file, update SAML_CERT, and restart n8n.
  2. Schedule a rotation alert (e.g., 30 days before expiry) with your monitoring tool.

6. Troubleshooting Checklist

Done? Action Why It Matters
☐ SAML_ENTITY_ID matches IdP <EntityDescriptor entityID> Prevents Issuer mismatch
☐ ACS URL (/auth/saml/callback) listed in IdP with POST binding Guarantees Assertion delivery
☐ IdP signing cert imported (SAML_CERT) and not expired Enables signature verification
☐ SAML_SIGNATURE_ALGORITHM set to the algorithm used by IdP Avoids “Invalid signature”
☐ NTP sync on both IdP and n8n hosts Stops time‑drift rejections
☐ SAML_DEBUG=true enabled only during investigation Provides raw SAML payload
☐ Browser console shows SAMLResponse POST field Confirms request reaches n8n
☐ Restart n8n after any .env change Forces config reload
☐ Backup .env and certificates before changes Protects against lock‑out

7. Production‑Grade EEFA Additions

  1. Fail‑Safe Admin Account – Create a local n8n user (username/password) before enabling SAML. Keep it disabled (USER_MANAGEMENT_DISABLED=true) but accessible via a secret URL (/admin/login). This provides an emergency backdoor if SSO mis‑config blocks all users.
  2. Read‑Only Certificate Mount – Docker‑Compose example:
volumes:
  - type: bind
    source: /opt/n8n/certs/idp_cert.pem
    target: /home/node/.n8n/certs/idp_cert.pem
    read_only: true
  1. Audit Logging – Temporarily set N8N_LOG_LEVEL=debug and forward logs to a SIEM. Capture SAML events with user IDs for compliance.
  2. Graceful Rollback – Keep a backup of the previous .env (.env.backup) and a one‑liner rollback script:
cp .env.backup .env && docker restart n8n

9. Next Steps

  • Implement SAML Single Logout (SLO) – ensure sessions terminate on both IdP and n8n.
  • Multi‑IdP SAML federation – configure n8n to accept assertions from several providers.
  • SAML attribute mapping – pull groups or roles into n8n for fine‑grained permissioning.

Conclusion

By aligning the Entity ID, ACS URL, and signing certificate, enabling precise logging, and following the checklist, you convert a generic “SAML error” into a reproducible fix. The added EEFA safeguards (fail‑safe admin, read‑only mounts, audit logging, and rollback strategy) ensure that SSO remains reliable and maintainable in production environments.

Must Read

Leave a Comment

Your email address will not be published. Required fields are marked *