Skip to main content

SAML Troubleshooting Guide

This guide covers common SAML SSO issues, error messages, and solutions.

Common Error Messages​

"SAML transaction expired"​

Symptom: User sees error after successful authentication

Cause: User took too long to complete authentication (>10 minutes)

Solution:

  1. Retry the SSO flow from the Service Provider
  2. Complete authentication within 10 minutes
  3. If issue persists, check system clocks (see Clock Skew section)

Technical Details:

  • SAML transactions have a 10-minute TTL
  • Transaction ID is stored in cache during SSO initiation
  • After 10 minutes, the transaction is purged

"Invalid signature"​

Symptom: Service Provider rejects SAML assertion

Cause:

  1. Clock skew between Signia and Service Provider
  2. Certificate mismatch (SP using old certificate)
  3. Signature verification failure

Solutions:

Check Clock Skew:

# On Service Provider server
date -u
# Compare with Signia server time (should be within 5 minutes)

Update Certificate:

  1. Download latest metadata from Signia
  2. Upload to Service Provider
  3. Verify fingerprint matches dashboard

Verify Configuration:

  • Entity ID in SP config matches Signia IdP Entity ID exactly
  • Certificate in SP matches certificate in metadata

"Unknown Service Provider"​

Symptom: User sees "Authentication Error: Unknown Service Provider"

Cause: Service Provider not configured in Signia dashboard

Solution:

  1. Log in to Signia ID dashboard
  2. Navigate to SAML → Service Providers
  3. Click Add Service Provider
  4. Enter Service Provider details (Entity ID, ACS URL)
  5. Ensure Enabled is checked
  6. Click Create Service Provider

Verify:

  • Entity ID in Service Provider configuration matches Entity ID in Signia dashboard exactly
  • No typos, extra spaces, or URL encoding differences

"SAML Connector client not found"​

Symptom: Internal error during SSO flow

Cause: SAML Connector OIDC client was accidentally deleted

Solution:

  • Auto-Healing: Signia automatically recreates the connector
  • No admin action required
  • SSO flow will continue normally

Prevention:

  • Never delete applications with saml-connector- prefix
  • System-managed applications are protected in dashboard

"Configuration Error: Unable to identify your tenant"​

Symptom: User sees error immediately

Cause: Tenant not configured or subdomain mismatch

Solution:

  1. Verify tenant subdomain is correct (e.g., acme.signiaauth.com)
  2. Check that SAML is enabled for this tenant
  3. Verify DNS resolution: 
    nslookup <tenant>.signiaauth.com

SSO Flow Debugging​

Step-by-Step Flow Analysis​

1. Service Provider Initiates SSO​

What happens:

  • SP generates SAML AuthnRequest XML
  • SP encodes request (base64 + optional deflate)
  • SP redirects user to Signia SSO URL with SAMLRequest parameter

Check:

# Decode SAMLRequest (HTTP-Redirect binding)
echo "<SAMLRequest_value>" | base64 -d | inflate | xmllint --format -

Common Issues:

  • Invalid Entity ID in AuthnRequest (must match SP config in Signia)
  • Invalid ACS URL (must match SP config in Signia)
  • Malformed XML

2. Signia Validates Request​

What happens:

  • Signia decodes and parses AuthnRequest
  • Validates Entity ID against configured Service Providers
  • Validates ACS URL matches configured SP
  • Checks signature (if request is signed)

Common Issues:

  • Entity ID mismatch → "Unknown Service Provider"
  • ACS URL mismatch → Validation fails
  • Expired request → "Request too old"

3. User Authenticates​

What happens:

  • Signia redirects user to /authorize endpoint
  • User sees standard Signia authentication UI
  • User authenticates with WebAuthn/Passkey or password
  • Signia creates user session

Common Issues:

  • User canceled authentication → SSO flow aborts
  • Authentication timeout → Retry flow
  • Network issues → User sees error page

4. Signia Generates Assertion​

What happens:

  • Signia retrieves SAML transaction from cache
  • Fetches user attributes (email, name, etc.)
  • Generates SAML Assertion XML with:
    • Issuer: Signia IdP Entity ID
    • Subject: User NameID
    • Conditions: NotBefore, NotOnOrAfter timestamps
    • AttributeStatement: User attributes
  • Signs assertion with IdP private key
  • Encodes assertion (base64)

Common Issues:

  • Transaction expired → "SAML transaction expired"
  • Certificate not found → Internal error (rare)
  • Attribute mapping issues → SP receives unexpected attributes

5. Signia Redirects to Service Provider​

What happens:

  • Signia POSTs SAMLResponse to SP's ACS URL
  • Response includes signed SAML Assertion
  • Optional RelayState parameter (SP-specific redirect)

Common Issues:

  • ACS URL unreachable → User sees browser error
  • HTTPS certificate invalid → Browser warning
  • SP doesn't accept POST binding → Configuration mismatch

6. Service Provider Validates Assertion​

What happens:

  • SP decodes SAMLResponse
  • SP verifies signature using IdP's public key
  • SP validates timestamps (NotBefore, NotOnOrAfter)
  • SP extracts user attributes
  • SP creates user session

Common Issues:

  • Signature verification fails → "Invalid signature"
  • Assertion expired → "Response too old"
  • Clock skew → Timestamps appear invalid
  • Attribute mapping issues → User profile incomplete

Specific Service Provider Issues​

Okta​

"SAML assertion audience mismatch"

  • Verify Okta's Entity ID matches Signia SP configuration
  • Check Okta SAML settings → General → SAML Settings

"Unable to sign in"

Azure AD​

"AADSTS750054: SAMLRequest or SAMLResponse must be present"

  • Azure AD initiated SSO not supported (use SP-initiated only)
  • Start SSO flow from Azure AD portal

"AADSTS50011: Reply URL mismatch"

  • Verify Reply URL in Azure AD matches Signia Entity ID
  • Azure AD requires exact match (case-sensitive)

AWS Cognito​

"Invalid SAML Response"

  • Verify Cognito Provider name matches Signia Entity ID
  • Check Cognito Attribute mapping (email is required)

"User pool client not configured correctly"

  • Verify Supported identity providers includes SAML provider
  • Check App client settings → Enabled Identity Providers

Clock Skew Issues​

SAML relies on accurate system clocks. If clocks are out of sync, assertions may be rejected.

Symptoms​

  • "Assertion expired" immediately after generation
  • "Response too old" when timestamps are valid
  • Intermittent authentication failures

Check Clock Skew​

# Check Signia server time (UTC)
curl -I https://<tenant>.signiaauth.com/saml/metadata | grep Date

# Check Service Provider server time
date -u

# Difference should be < 5 minutes

Solutions​

Sync System Clocks:

# Ubuntu/Debian
sudo systemctl restart systemd-timesyncd

# CentOS/RHEL
sudo systemctl restart chronyd

Configure Clock Skew Tolerance:

  • Most Service Providers allow 5-minute clock skew
  • Check SP documentation for configuration options

Verify NTP Configuration:

timedatectl status
# Ensure NTP is enabled

Certificate Issues​

"Certificate expired"​

Check Expiration:

  1. Log in to Signia ID dashboard
  2. Navigate to SAML → Identity Provider Information
  3. Check Certificate Expiration field

Renew Certificate (coming in future release):

  1. Generate new certificate in dashboard
  2. Download updated metadata
  3. Update all Service Providers with new metadata

"Certificate fingerprint mismatch"​

Verify Fingerprint:

  1. Check fingerprint in Signia dashboard (SHA-256)
  2. Compare with fingerprint in Service Provider configuration
  3. If mismatched, update SP with current metadata

Extract Fingerprint from Metadata:

# Extract certificate
xmllint --xpath "//*[local-name()='X509Certificate']/text()" metadata.xml > cert.txt

# Calculate SHA-256 fingerprint
echo "-----BEGIN CERTIFICATE-----" > cert.pem
cat cert.txt >> cert.pem
echo "\n-----END CERTIFICATE-----" >> cert.pem
openssl x509 -in cert.pem -fingerprint -sha256 -noout

Network & Connectivity Issues​

"Unable to reach SSO endpoint"​

Check DNS Resolution:

nslookup <tenant>.signiaauth.com
# Should resolve to Signia servers

Check HTTPS Connectivity:

curl -v https://<tenant>.signiaauth.com/saml/metadata
# Should return 200 OK with XML

Check Firewall Rules:

  • Ensure Service Provider can reach Signia on port 443
  • Check for corporate proxies or firewalls blocking traffic

"SSL/TLS handshake failed"​

Check Certificate Validity:

openssl s_client -connect <tenant>.signiaauth.com:443 -servername <tenant>.signiaauth.com

Common Causes:

  • Expired SSL certificate (Signia infrastructure)
  • TLS version mismatch (Signia requires TLS 1.2+)
  • SNI not supported by client

Debugging Tools​

Browser Developer Tools​

Network Tab:

  1. Open Developer Tools (F12)
  2. Navigate to Network tab
  3. Initiate SSO flow
  4. Look for redirects to Signia SSO URL
  5. Check POST to SP's ACS URL

Console Tab:

  • Look for JavaScript errors
  • Check for CORS issues
  • Verify redirects complete successfully

SAML Tracer (Browser Extension)​

Installation:

Usage:

  1. Install extension
  2. Open SAML Tracer
  3. Initiate SSO flow
  4. View decoded SAML messages
  5. Inspect assertions, signatures, timestamps

Command-Line Tools​

Decode SAMLRequest:

echo "<SAMLRequest>" | base64 -d | zlib-flate -uncompress | xmllint --format -

Decode SAMLResponse:

echo "<SAMLResponse>" | base64 -d | xmllint --format -

Verify Signature:

# Extract assertion from response
xmllint --xpath "//*[local-name()='Assertion']" response.xml > assertion.xml

# Verify signature (requires xmlsec1)
xmlsec1 --verify --pubkey-cert-pem cert.pem assertion.xml

Getting Help​

Collect Diagnostic Information​

When contacting support, provide:

  1. Tenant subdomain: <tenant>.signiaauth.com
  2. Service Provider details: Name, Entity ID, ACS URL
  3. Error message: Exact text shown to user
  4. SAML Tracer logs: Exported from browser extension
  5. Timestamp: When error occurred (UTC)
  6. Browser: Name and version
  7. Steps to reproduce: Detailed description

Enable Debug Logging​

Signia Backend (for self-hosted deployments):

# Set log level to debug
export RUST_LOG=debug

# Restart auth backend
systemctl restart signia-auth-backend

Check Logs:

# Auth backend logs
journalctl -u signia-auth-backend -f | grep SAML

# ID backend logs
journalctl -u signia-id-backend -f | grep SAML

Support Channels​