Solución de problemas de SSO

Esta guía cubre los problemas comunes que puede encontrar al configurar o usar Single Sign-On con Zenovay, junto con sus soluciones.

Errores de SAML 2.0

"SAML signature verification failed"

Causa: El certificado X.509 en Zenovay no coincide con el certificado que su proveedor de identidad utilizó para firmar la respuesta SAML.

Solución:

1. Descargue una copia nueva del certificado de firma de su IdP
2. En Zenovay, vaya a Settings → Security → SSO
3. Edite el proveedor SAML y reemplace el certificado
4. Asegúrese de haber copiado el certificado completo incluyendo -----BEGIN CERTIFICATE----- y -----END CERTIFICATE-----

"SAML digest mismatch"

Causa: La respuesta SAML fue modificada en tránsito o el certificado incorrecto está configurado.

Solución:

1. Verifique que el certificado en Zenovay coincida con el certificado de firma activo en su IdP
2. Si su IdP ha rotado recientemente los certificados, descargue el nuevo
3. Asegúrese de que no haya proxies o middleware modificando la respuesta SAML

"Referenced element not found"

Causa: La respuesta SAML no contiene el elemento firmado esperado.

Solución:

1. Verifique que su IdP esté enviando una respuesta SAML 2.0 estándar
2. Compruebe que la respuesta incluye un elemento Assertion con un atributo ID válido
3. Contacte a su administrador de IdP si el problema persiste

"Entity ID mismatch" o "Audience mismatch"

Causa: El SP Entity ID configurado en su IdP no coincide con lo que Zenovay espera.

Solución:

• Establezca el SP Entity ID / Audience URI en su IdP exactamente a: https://auth.zenovay.com
• No incluya una barra diagonal al final ni ninguna ruta

"Invalid ACS URL" o "Reply URL mismatch"

Causa: La URL de ACS en su IdP no coincide con el punto final de devolución de llamadas de Zenovay.

Solución:

• Establezca la URL de ACS exactamente a: https://auth.zenovay.com/api/sso/saml/callback
• Asegúrese de que no haya una barra diagonal al final

"NameID not found" o "Email not provided"

Causa: La respuesta SAML no contiene la dirección de correo electrónico del usuario en el formato esperado.

Solución:

1. Establezca el NameID format a EmailAddress en su IdP
2. Asegúrese de que el NameID value se asigne a la dirección de correo electrónico del usuario
3. Verifique que el usuario tenga una dirección de correo electrónico válida en su directorio de IdP

Errores de OAuth 2.0 / OIDC

"Invalid redirect URI" o "Redirect URI mismatch"

Causa: El URI de redireccionamiento configurado en su IdP no coincide con lo que Zenovay envía.

Solución:

• Establezca el URI de redireccionamiento exactamente a: https://auth.zenovay.com/api/sso/oauth/callback
• Asegúrese de que no haya una barra diagonal al final
• El URI debe ser una coincidencia exacta (distingue mayúsculas y minúsculas)

"Invalid client credentials"

Causa: El Client ID o Client Secret ingresado en Zenovay es incorrecto.

Solución:

1. Verifique el Client ID y Client Secret en su panel de IdP
2. Si el secreto ha expirado, genere uno nuevo
3. Actualice los valores en Zenovay

"OIDC discovery failed"

Causa: Zenovay no puede alcanzar el punto final de descubrimiento de OpenID Connect en su URL de emisor.

Solución:

1. Verifique que la URL de emisor sea correcta
2. Pruebe la URL de descubrimiento en su navegador: {issuer-url}/.well-known/openid-configuration
3. Algunos IdP requieren una barra diagonal al final en la URL de emisor (por ejemplo, Auth0: https://tenant.us.auth0.com/)
4. Asegúrese de que su IdP sea públicamente accesible

"Token verification failed"

Causa: El token de ID de su IdP no pudo ser verificado.

Solución:

1. Asegúrese de que el punto final JWKS de su IdP sea accesible
2. Compruebe que el algoritmo de firma del token coincida con lo que su IdP anuncia
3. Verifique que la reclamación aud (audience) en el token coincida con el Client ID

"State parameter mismatch"

Causa: El estado de autenticación se perdió o fue modificado, típicamente debido a problemas de sesión.

Solución:

1. Borre las cookies del navegador e intente de nuevo
2. Asegúrese de que no esté utilizando una extensión del navegador que bloquee las cookies
3. Intente en una ventana incógnita/privada

Problemas de verificación de dominio

"Domain not verified"

Causa: Su dominio de correo electrónico no ha sido verificado para SSO.

Solución:

1. Vaya a Settings → Security → SSO
2. Haga clic en su proveedor de SSO
3. Haga clic en Add Domain e ingrese su dominio de correo electrónico
4. Siga los pasos de verificación de DNS
5. Permita tiempo para la propagación de DNS (hasta 48 horas)

"Domain already in use"

Causa: El dominio de correo electrónico ya está vinculado a otro proveedor de SSO u organización.

Solución:

1. Verifique si otro proveedor de SSO en su organización ya usa este dominio
2. Elimine el dominio del otro proveedor primero
3. Si el dominio está vinculado a una organización diferente, contacte a [email protected]

Problemas de certificados

Expiración de certificado

Los certificados de firma SAML tienen una fecha de vencimiento. Cuando vencen, la autenticación de SSO fallará.

Cómo verificar:

1. Verifique su panel de IdP para la fecha de vencimiento del certificado
2. Establezca un recordatorio de calendario 30 días antes del vencimiento

Cómo actualizar:

1. Descargue el nuevo certificado de su IdP
2. En Zenovay, edite el proveedor de SSO
3. Reemplace el certificado y guarde
4. Pruebe la conexión

Formato del certificado

Zenovay espera el certificado X.509 en formato PEM:

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

• Incluya las líneas BEGIN y END
• No incluya espacios en blanco adicionales ni encabezados
• Si su IdP proporciona un archivo .cer o .der, conviértalo a formato PEM primero

Problemas generales

"SSO provider not found"

Causa: El dominio de correo electrónico ingresado en el inicio de sesión no coincide con ningún proveedor de SSO configurado.

Solución:

1. Verifique que el dominio se haya agregado y verificado en el proveedor de SSO en Zenovay
2. Asegúrese de que el usuario esté ingresando un correo electrónico con el dominio correcto

Los usuarios no pueden iniciar sesión después de la aplicación de SSO

Causa: SSO está aplicado pero los usuarios no pueden autenticarse con el IdP.

Solución:

1. Desactive temporalmente la aplicación de SSO en Settings → Security → SSO
2. Inicie sesión con correo electrónico/contraseña para acceder a la configuración
3. Corrija la configuración de SSO
4. Vuelva a aplicar la autenticación

Los nuevos usuarios no se crean

Causa: El usuario existe en su IdP pero no tiene una cuenta de Zenovay.

Solución: Zenovay aprovisiona automáticamente nuevas cuentas de usuario en el primer inicio de sesión de SSO. Si esto no está sucediendo:

1. Verifique que la respuesta SAML o el token OIDC incluya la dirección de correo electrónico del usuario
2. Compruebe que el dominio de correo electrónico coincida con el dominio verificado
3. Asegúrese de que el usuario esté asignado a la aplicación Zenovay en su IdP

Lista de verificación de prueba

Antes de aplicar SSO, verifique:

• El proveedor de SSO está configurado en Zenovay con valores de IdP correctos
• El dominio de correo electrónico está verificado
• Los usuarios están asignados a la aplicación en su IdP
• La prueba de inicio de sesión funciona en una ventana incógnita
• El aprovisionamiento de nuevos usuarios funciona (pruebe con un usuario que aún no tenga una cuenta de Zenovay)
• Al menos un propietario pueda iniciar sesión por correo electrónico/contraseña como respaldo

Obtener ayuda

Si aún está experimentando problemas:

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

Al contactar al soporte, incluya:

1. El nombre de su proveedor de identidad y protocolo (SAML/OAuth/OIDC)
2. El mensaje de error exacto que ve
3. Si esto es una configuración nueva o una existente que dejó de funcionar
4. Cualquier cambio reciente en su configuración de IdP