Solución de problemas para iniciar sesión en Payhawk mediante SSO basado en SAML

Si tienes problemas para iniciar sesión en Payhawk mediante inicio de sesión único (SSO) basado en SAML, esta guía te ayudará a recopilar información de diagnóstico que puede acelerar la solución de problemas y la resolución.

La mayoría de los problemas de inicio de sesión mediante SSO se producen cuando las cuentas de usuario o las configuraciones de SSO no están correctamente configuradas por el administrador en su proveedor de identidades (IdP) o en Payhawk.

Captura de los datos necesarios

Los siguientes pasos te ayudarán a capturar los datos necesarios para identificar la causa fundamental:.

Paso 1: Generar un archivo HAR

Un archivo HAR (archivo HTTP) captura toda la actividad de la red durante su intento de inicio de sesión, incluyendo redireccionamientos, solicitudes y respuestas, ayudando así a diagnosticar problemas de conectividad, redireccionamiento o flujo de autenticación. Para crear el archivo necesario para solucionar el problema, consulta el artículo sobre la generación de archivos HAR.

Puedes utilizar el archivo HAR en los siguientes casos:

Cuando tu inicio de sesión falla sin un mensaje de error .
Si te quedas atascado en una pantalla en blanco o de carga .
En el caso de que se produzca un bucle de redirección SSO

Paso 2: Capturar la respuesta SAML

La respuesta SAML es el mensaje de autenticación enviado desde tu IdP a Payhawk. Contiene información sobre el usuario, la aserción y cualquier error que pueda haber ocurrido durante el proceso de autenticación.

Capturar esta respuesta permite identificar los desajustes de configuración, las reclamaciones que faltan o las afirmaciones no válidas..

Puedes capturar la respuesta SAML de las siguientes formas:

Utilizando las herramientas para desarrolladores de tu navegador

Utilizar las herramientas para desarrolladores del navegador es el método más fiable para capturar una respuesta SAML durante un inicio de sesión en vivo:

Abre las herramientas para desarrolladores de tu navegador, pulsa F12 o haz clic con el botón derecho y selecciona Inspeccionar.
Ve a la pestaña Red.
Inicia un inicio de sesión mediante SSO en Payhawk desde tu proveedor de identidad.
Busca una solicitud POST dirigida a https://id.payhawk.com/saml2/idpresponse.
Haz clic en esa solicitud y ve a la sección Carga o Datos del formulario.
Localiza el parámetro SAMLResponse. El valor será una cadena codificada en Base64.
Copia toda la cadena Base64.
Decodifícala utilizando un decodificador Base64 en línea, como este, para ver el XML completo de la aserción SAML..

Deberás buscar la siguiente información en el XML descodificado:

El <saml:Issuer>tiene que coincidir con el ID de entidad de tu IdP.
El <saml:Audience>tiene que coincidir con el ID de entidad de Payhawk.
El <saml:NameID>tiene que contener el correo electrónico o identificador del usuario..
Mensajes de error o condiciones no válidas.

Utilizando una extensión del navegador

Las extensiones del navegador pueden simplificar la captura y descodificación automática de mensajes SAML.

Se recomiendan las siguientes extensiones:

SAML-tracer (Firefox): instálalo aquí.
SAML Chrome Panel (Chrome): instálalo aquí.

Para utilizar la extensión del navegador para solucionar el problema:

Instala la extensión.
Abre el panel de extensiones (normalmente se encuentra en las herramientas para desarrolladores o como icono de la barra de herramientas del navegador).
Iniciar el flujo de inicio de sesión mediante SSO.
La extensión capturará y mostrará automáticamente la solicitud y la respuesta SAML.
Exporta o copia el XML de respuesta SAML descodificado.

Comprobando los registros de tu IdP

Algunos IdP, como Microsoft Entra ID (Azure AD), Okta o Google Workspace, ofrecen registros de inicio de sesión detallados que pueden incluir la aserción SAML o las reclamaciones enviadas a Payhawk..

Si utilizas Microsoft Entra ID:

Inicia sesión en el Portal Azure..
Ve a Azure Active Directory > Aplicaciones empresariales > [Tu aplicación Payhawk].
Ve a Registros de inicio de sesión.
Encuentra el intento de inicio de sesión fallido y haz clic para ver los detalles.
Buscar detalles de token SAML o reclamaciones emitidas.

Si utilizas otros IdP, consulta la documentación oficial de tu IdP para acceder a los registros de inicio de sesión o de auditoría.

Paso 3: Compartir los datos de diagnóstico con el soporte de Payhawk.

Una vez hayas recopilado el archivo HAR y la respuesta SAML, envíalos a support@payhawk.com o en el chat para que el soporte Payhawk los analice:

En tu mensaje, debes incluir la siguiente información:

Una descripción del problema (por ejemplo, «El inicio de sesión mediante SSO falla con el error X»).
El archivo HAR
El XML de respuesta SAML descodificado
El nombre de tu empresa y el correo electrónico del usuario

Problemas comunes de SAML y qué hay que comprobar

Problema	Posible causa	Qué hay que comprobar
El inicio de sesión falla silenciosamente	Usuario no asignado a la aplicación Payhawk en el IdP	Verifica que el usuario está asignado en el IdP (por ejemplo, Azure AD, Okta).
Respuesta SAML no válida	ID de entidad o puntos finales mal configurados	Comprueba que el ID de entidad de Payhawk y la URL de ACS coincidan con la configuración de tu IdP.
Usuario no encontrado	El correo electrónico o NameID no coinciden	Comprueba que el NameID SAML coincida con el correo electrónico de Payhawk del usuario.
Error de certificado	El certificado de firma está caducado o no coincide	Comprueba que el certificado IdP esté actualizado en la configuración del SSO de Payhawk.
Bucle de redireccionamiento	La URL de inicio SSO es incorrecta	Confirma que estás utilizando la URL de inicio de sesión mediante SSO en Payhawk correcta.