Guía de Configuración de Autenticación SAML entre Fracttal y Keycloak

Requisitos Previos

Acceso administrativo a Keycloak (versión 16.1.1 o superior).
Acceso administrativo a Fracttal.
URL base de Fracttal: https://app.fracttal.com
Nombre clave de configuración SAML (por ejemplo, en este documento uso: fracttalkeykloak). Este valor debe ser único y coincidir con el configurado en Keycloak.

Creación del Cliente en Keycloak

Inicie sesión en la consola de administración de Keycloak.
En el menú lateral, seleccione: Configure → Clients.
Haga clic en el botón 'Create'.

En el campo 'Client ID', ingrese el identificador del cliente: fracttal-app. (es el valor que uso para el ejemplo, pero es a criterio de quien configure. Lo importante es que coincida con el issuer configurado en Fracttal).
Seleccione 'saml' como Client Protocol.
Presione 'Save' para continuar.

Configuración del Cliente SAML

Una vez creado el cliente, configure los parámetros en la pestaña 'Settings' de la siguiente manera

Parámetro	Valor	Descripción
Client ID	fracttal-app	Identificador único del cliente
Enabled	ON	Activa el cliente
Client Protocol	saml	Define el protocolo SAML.
Sign Assertions	ON	Este parámetro indica si Keycloak debe firmar las aserciones SAML
Signature Algorithm	RSA_SHA256	Define el algoritmo criptográfico utilizado para generar la firma digital en los mensajes SAML
SAML Signature Key Name	KEYID	Especifica cómo Keycloak identifica la clave usada para firmar el mensaje SAML dentro del XML
Canonicalization Method	EXCLUSIVE	Define el método de canonicalización XML, que es la forma en la que se normaliza el documento antes de aplicar la firma digital
Force POST Binding	ON	Fuerza el método POST para respuestas SAML.
Front Channel Logout	ON	Habilita el cierre de sesión coordinado.
Name ID Format	email	Envía el identificador de usuario como correo electrónico.
Valid Redirect URIs	https://app.fracttal.com/rpc/auth/samlcallback?codesaml=fracttalkeykloak&id_server=AMERICAN	URI de retorno hacia Fracttal.
Base URL	https://app.fracttal.com	URL base del servicio SP.
Assertion Consumer Service POST Binding URL	https://app.fracttal.com/rpc/auth/samlcallback?codesaml=fracttalkeykloak	Endpoint donde Fracttal recibe las respuestas SAML.

Nota

El valor 'fracttalkeykloak' debe coincidir con el nombre clave configurado en Fracttal. Si se utiliza otro nombre, este debe reemplazarse en todos los campos donde aparezca.

Tampoco es requerido realizar mapeos personalizados de campos, sólo con indicar que el NameID Format es email debe funcionar.

Configuración en Fracttal

Para registrar el Identity Provider (Keycloak) en Fracttal:

Ingrese a Fracttal con un usuario administrador.
Vaya a Configuración → Seguridad → SAML 2.0.
Complete los campos de acuerdo con la siguiente tabla.

Campo	Valor
Conexión/Nickname	fracttalkeykloak
Issuer	fracttal-app
Single Sign-On URL	http://localhost:8080/auth/realms/master/protocol/saml
Single Logout URL	http://localhost:8080/auth/realms/master/protocol/saml
Certificate	(Certificado X.509 exportado desde Keycloak)

El campo 'Issuer' debe tener el mismo valor que el Client ID del cliente configurado en Keycloak.

Los campos de URLs (SSO y Logout) se obtienen desde el metadata del Identity Provider en Keycloak, accesible desde 'Realm Settings → General → SAML 2.0 Identity Provider Metadata'.

Exportar Metadatos del IdP

En la vista del Realm, abra la pestaña 'General'.

Haga clic en 'SAML 2.0 Identity Provider Metadata'.
Copie o descargue el contenido XML.
Extraiga el certificado y las URLs (SingleSignOnService y SingleLogoutService) del XML.
Estos valores deben coincidir con los configurados en Fracttal.

Pruebas y Validación

Acceda a Fracttal e intente iniciar sesión con el método SAML configurado.
Verifique que se redirija al login de Keycloak.
Inicie sesión con las credenciales del IdP.
Si la autenticación es exitosa, el usuario ingresará automáticamente a Fracttal.