SSO Troubleshooting

This guide covers common issues you may encounter when setting up or using Single Sign-On with Zenovay, along with their solutions.

SAML 2.0 Errors

"SAML signature verification failed"

Cause: The X.509 certificate in Zenovay does not match the certificate your identity provider used to sign the SAML response.

Solution:

1. Download a fresh copy of the signing certificate from your IdP
2. In Zenovay, go to Settings > Authentication > SSO
3. Edit the SAML provider and replace the certificate
4. Ensure you copied the full certificate including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----

"SAML digest mismatch"

Cause: The SAML response was modified in transit or the wrong certificate is configured.

Solution:

1. Verify the certificate in Zenovay matches the active signing certificate in your IdP
2. If your IdP recently rotated certificates, download the new one
3. Ensure there are no proxies or middleware modifying the SAML response

"Referenced element not found"

Cause: The SAML response does not contain the expected signed element.

Solution:

1. Verify your IdP is sending a standard SAML 2.0 response
2. Check that the response includes an Assertion element with a valid ID attribute
3. Contact your IdP administrator if the issue persists

"Entity ID mismatch" or "Audience mismatch"

Cause: The SP Entity ID configured in your IdP does not match what Zenovay expects.

Solution:

• Set the SP Entity ID / Audience URI in your IdP to exactly: https://auth.zenovay.com
• Do not include a trailing slash or any path

"Invalid ACS URL" or "Reply URL mismatch"

Cause: The ACS URL in your IdP does not match Zenovay's callback endpoint.

Solution:

• Set the ACS URL to exactly: https://auth.zenovay.com/api/sso/saml/callback
• Ensure there is no trailing slash

"NameID not found" or "Email not provided"

Cause: The SAML response does not contain the user's email address in the expected format.

Solution:

1. Set the NameID format to EmailAddress in your IdP
2. Ensure the NameID value maps to the user's email address
3. Verify the user has a valid email address in your IdP directory

OAuth 2.0 / OIDC Errors

"Invalid redirect URI" or "Redirect URI mismatch"

Cause: The redirect URI configured in your IdP does not match what Zenovay sends.

Solution:

• Set the redirect URI to exactly: https://auth.zenovay.com/api/sso/oauth/callback
• Ensure there is no trailing slash
• The URI must be an exact match (case-sensitive)

"Invalid client credentials"

Cause: The Client ID or Client Secret entered in Zenovay is incorrect.

Solution:

1. Verify the Client ID and Client Secret in your IdP dashboard
2. If the secret has expired, generate a new one
3. Update the values in Zenovay

"OIDC discovery failed"

Cause: Zenovay cannot reach the OpenID Connect discovery endpoint at your Issuer URL.

Solution:

1. Verify the Issuer URL is correct
2. Test the discovery URL in your browser: {issuer-url}/.well-known/openid-configuration
3. Some IdPs require a trailing slash in the Issuer URL (e.g., Auth0: https://tenant.us.auth0.com/)
4. Ensure your IdP is publicly accessible

"Token verification failed"

Cause: The ID token from your IdP could not be verified.

Solution:

1. Ensure your IdP's JWKS endpoint is accessible
2. Check that the token signing algorithm matches what your IdP advertises
3. Verify the aud (audience) claim in the token matches the Client ID

"State parameter mismatch"

Cause: The authentication state was lost or tampered with, typically due to session issues.

Solution:

1. Clear browser cookies and try again
2. Ensure you are not using a browser extension that blocks cookies
3. Try in an incognito/private window

Domain Verification Issues

"Domain not verified"

Cause: Your email domain has not been verified for SSO.

Solution:

1. Go to Settings > Authentication > SSO
2. Click on your SSO provider
3. Click Add Domain and enter your email domain
4. Follow the DNS verification steps
5. Allow time for DNS propagation (up to 48 hours)

"Domain already in use"

Cause: The email domain is already linked to another SSO provider or organization.

Solution:

1. Check if another SSO provider in your organization already uses this domain
2. Remove the domain from the other provider first
3. If the domain is linked to a different organization, contact [email protected]

Certificate Issues

Certificate Expiration

SAML signing certificates have an expiration date. When they expire, SSO authentication will fail.

How to check:

1. Check your IdP dashboard for the certificate expiration date
2. Set a calendar reminder 30 days before expiration

How to update:

1. Download the new certificate from your IdP
2. In Zenovay, edit the SSO provider
3. Replace the certificate and save
4. Test the connection

Certificate Format

Zenovay expects the X.509 certificate in PEM format:

-----BEGIN CERTIFICATE-----
MIIDpDCCAoygAwIBAgIGAX...
(base64 encoded certificate data)
...
-----END CERTIFICATE-----

• Include the BEGIN and END lines
• Do not include any extra whitespace or headers
• If your IdP provides a .cer or .der file, convert it to PEM format first

General Issues

"SSO provider not found"

Cause: The email domain entered at login does not match any configured SSO provider.

Solution:

1. Verify the domain is added and verified on the SSO provider in Zenovay
2. Ensure the user is entering an email with the correct domain

Users Cannot Sign In After SSO Enforcement

Cause: SSO is enforced but users are unable to authenticate with the IdP.

Solution:

1. Temporarily disable SSO enforcement in Zenovay settings
2. Sign in with email/password to access settings
3. Fix the SSO configuration
4. Re-enable enforcement

New Users Not Being Created

Cause: The user exists in your IdP but does not have a Zenovay account.

Solution: Zenovay automatically provisions new user accounts on first SSO login. If this is not happening:

1. Verify the SAML response or OIDC token includes the user's email address
2. Check that the email domain matches the verified domain
3. Ensure the user is assigned to the Zenovay application in your IdP

Testing Checklist

Before enforcing SSO, verify:

• SSO provider is configured in Zenovay with correct IdP values
• Email domain is verified
• Users are assigned to the application in your IdP
• Test login works in an incognito window
• New user provisioning works (test with a user who does not yet have a Zenovay account)
• At least one Owner can still sign in via email/password as a backup

Getting Help

If you are still experiencing issues:

• Email: [email protected]
• Enterprise Support: [email protected]

When contacting support, include:

1. Your identity provider name and protocol (SAML/OAuth/OIDC)
2. The exact error message you see
3. Whether this is a new setup or an existing one that stopped working
4. Any recent changes to your IdP configuration