SAML Troubleshooting

Troubleshooting

Common Issues

“No active SAML certificate found”

• Cause: Certificate not generated or expired
• Solution: Generate new certificate using POST /saml/certificate endpoint

“SAML is not enabled for this service”

• Cause: SAML configuration not created or disabled
• Solution: Create/enable SAML configuration using POST /saml endpoint

“Invalid or expired SAML state”

• Cause: SAML state expired (15 minute timeout) or already used
• Solution: User should restart login flow from Service Provider

Service Provider rejects SAMLResponse

• Cause: Signature validation failure, certificate mismatch, or configuration mismatch
• Solution:
  1. Verify SP has correct IdP certificate
  2. Check entity_id matches SP configuration
  3. Verify acs_url is correct
  4. Ensure both sign_assertions and sign_response are enabled

IdP-Initiated flow not working

• Cause: Some Service Providers don’t accept unsolicited responses
• Solution: Check SP documentation, use SP-initiated flow instead

Audit Trail

All SAML configuration changes are logged in the organization audit log:

# View one SAML event category (repeat with the actions below as needed)
curl "https://sso.example.com/api/organizations/acme-corp/audit-log?action=saml.certificate_generated" \
  -H "Authorization: Bearer {jwt_token}"

SAML Audit Events:

• saml.configured with detail action saml_configured or saml_disabled
• saml.deleted with detail action saml_config_deleted
• saml.certificate_generated
• saml.certificate_overlap_retired