Introducción
Las empresas que usan Affilentra en modo self‑hosted suelen necesitar autenticación centralizada mediante SSO (SAML u OIDC) para unificar la gestión de usuarios, el cumplimiento y la facilidad de uso. Esta guía muestra cómo conectar Affilentra de modo que los roles queden claramente separados, los usuarios se aprovisionen automáticamente y los ciclos de vida de sesiones y tokens se gestionen de forma segura. Enfoque práctico, orientado por roles y directamente aplicable.
Resumen: ¿Por qué SSO en Affilentra?
Affilentra ofrece una arquitectura de roles con tres actores centrales: operador del software (operador de la plataforma), comerciantes (Merchants) y socios (Publisher/Creator). SSO aporta tres ventajas: gestión central de identidades, control de acceso consistente y auditorías simplificadas. En configuración self‑hosted conserva el control total (licencia perpetua, sin participación en ingresos) y aun así se integra con infraestructuras IdP existentes.
Requisitos y decisiones arquitectónicas
- Elija el IdP: SAML‑IdP (p. ej. ADFS, Shibboleth) u OIDC/OAuth‑provider (p. ej. Keycloak, Auth0, Azure AD).
- Decida el modelo de autenticación: solo IdP (central) o modo híbrido (cuenta local como respaldo).
- Prepare canales de conexión seguros: HTTPS, certificados actualizados, sincronización de tiempo/reloj.
Pasos para la integración SAML
1) Intercambio de metadatos: Genere los metadatos del Service Provider (SP) de Affilentra (EntityID, Assertion Consumer Service URL, formato NameID deseado) e importe los metadatos del IdP en Affilentra.
2) Firma y cifrado: Active la verificación de firmas de las Assertions y compruebe los certificados de firma del IdP mediante huella/PEM. Si está disponible, utilice Assertions cifradas.
3) Definir atributos: Solicite al IdP que envíe estos atributos:
- uid o sub – identificador único del usuario
- email – contacto/clave primaria para el emparejamiento
- roles u entitlement – roles/grupos
- givenName / sn – información para mostrar
4) Mapeo en Affilentra: Configure en Affilentra cómo se traducen los atributos a roles internos (ver mapeo de roles más abajo). Active opcionalmente el aprovisionamiento Just‑In‑Time para que los usuarios nuevos se creen automáticamente con permisos básicos.
5) Pruebas: Valide el contenido de las Assertions, las ventanas temporales (NotBefore/NotOnOrAfter) y compruebe el cierre de sesión (iniciado por IdP / iniciado por SP).
Pasos para la integración OIDC
1) Discovery y credenciales: Inserte Client‑ID, Client‑Secret y Redirect URI tanto en el IdP como en Affilentra. Use la .well‑known/openid-configuration para automatizar la configuración.
2) Scopes y Claims: Solicite al menos openid y profile/email. Claims adicionales para roles: roles, groups o claims personalizados a través de UserInfo.
3) Validación del ID Token: Verifique issuer, audience (client_id), nonce (en Authorization Code Flow opcional si es SPA) y la firma (JWKs).
4) Gestión de tokens: Utilice Authorization Code Flow con PKCE para clientes web y Refresh Tokens rotativos para sesiones más largas (ver Token‑Lifecycle).
5) Provisionamiento y mapeo: Una vez que tenga ID Token / UserInfo, mapee los claims a cuentas de usuario internas como en SAML.
Mapeo de roles: asignación precisa en Affilentra
El objetivo: cada rol externo conduce de forma determinista a un rol interno con permisos adecuados.
- Operador del software: Asigne este rol solo si el IdP proporciona el claim admin_level o una membresía de grupo específica. Los operadores del software tienen permisos de administrador en toda la plataforma; esta asignación debe revisarse estrictamente y limitarse a unos pocos grupos del IdP.
- Comerciante (Merchant): Mapee grupos del IdP o un claim merchant_id → cuenta de comerciante interna. Las cuentas de comerciantes deben vincularse a un objeto Merchant separado en Affilentra.
- Partner: Los roles de asociación (partner, publisher) deberían incluir un claim partner_id o affiliation. Los partners reciben enlaces de seguimiento personales y acceso al historial de pagos; esta asignación es muy granular.
Reglas prácticas:
- Prioridad en roles múltiples: Defina una jerarquía (p. ej. Operador del software > Comerciante > Partner) o permita la vinculación de múltiples cuentas.
- Vinculación: Use sub/uid + email para la asignación. Si ya existe una cuenta local, ofrezca un flujo de enlace/match en lugar de crear una nueva cuenta.
- Principio de mínimo privilegio: Asigne por defecto solo el rol básico; derechos ampliados mediante grupos del IdP o revisión manual.
Gestionar de forma segura el ciclo de vida de sesiones y tokens
El control seguro de sesiones es crucial para que el SSO no se convierta en un punto débil.
Access Tokens
- De corta duración: Los Access Tokens deberían expirar pronto (p. ej. minutos hasta pocas horas).
- Verificación: Validación del lado del servidor (firma, aud, exp) en cada petición relevante.
Refresh Tokens
- Rotación: Implemente refresh tokens rotativos para que los tokens comprometidos queden invalidados.
- Almacenamiento seguro: Almacene los Refresh Tokens solo del lado del servidor o en Cookies HttpOnly y Secure; evite el almacenamiento en el cliente en aplicaciones web.
Sesiones
- Store de sesión del lado del servidor: Prefiera un store de sesión centralizado y cifrado (Redis, DB) en lugar de usar únicamente JWT para sesiones largas.
- Timeout inactivo vs absoluto: Combine un Idle‑Timeout (p. ej. 30‑60 min) y un Absolute Timeout (p. ej. varias horas/días) según los requisitos de seguridad.
Logout y revocación
- Cierre de sesión iniciado por RP: Implemente redirecciones al endpoint de cierre de sesión del IdP y elimine las sesiones locales.
- Cierre de sesión iniciado por IdP (SLO): Soporte SAML Single Logout o OIDC Front/Backchannel Logout para la desconexión centralizada.
- Revocación de tokens: Utilice los endpoints de revocación de tokens del IdP, cuando sea necesario ante revocación de usuario o compromiso.
Seguridad & Operaciones
- Monitorización & Auditoría: Registre inicios de sesión, contenidos de Assertions/ID Token (no sensibles), revocaciones de tokens y eventos de aprovisionamiento. Conserve el rastro de auditoría para trazabilidad.
- Sincronización de reloj: Asegure NTP; las comprobaciones de autenticación son sensibles al tiempo.
- Principio de privilegio mínimo para administradores: Pocos accesos con permisos a nivel de plataforma; forzar Autenticación Multifactor (MFA) para administradores.
- Pruebas: Verifique failover (caída del IdP), desajuste de tiempo, variaciones de claims y atributos inesperados.
Ejemplo práctico: Flujo típico de integración
- Seleccionar IdP y exportar metadatos/configuración.
- Crear SP/Client en Affilentra, introducir URL de Redirect/ACS, cargar certificados.
- Configurar el mapeo de atributos en Affilentra: sub → extern_id, email → email, roles → role.
- Activar Provisionamiento Just‑In‑Time + configurar permisos iniciales.
- Configurar la política de Token/Sesión (tiempos de vida, rotación de Refresh, manejo de logout).
- Probar End‑to‑End con una cuenta de operador de software, una de comerciante y una de partner.
- Activar el registro de auditoría y documentarlo.
Ventaja de Affilentra en la integración SSO
Affilentra (ediciones PRO & NETWORK, self‑hosted, licencia perpetua) proporciona la estructura de plataforma basada en roles y los hooks para proveedores SAML/OIDC. La clara separación entre operador de software, comerciante y partner facilita el mapeo de roles, y la instalación self‑hosted le otorga control total sobre el almacenamiento de tokens, políticas de sesión y auditorías sin participación en ingresos.
Conclusión y siguiente paso
La integración de SAML u OIDC en Affilentra ofrece funciones seguras y escalables de Single Sign‑On preservando la separación de roles entre operador de plataforma, comerciantes y partners. Enfocarse en un mapeo correcto de claims/atributos, tokens de acceso de corta duración, estrategias seguras para refresh tokens y procesos de auditoría exhaustivos reduce riesgos y aumenta la fiabilidad operativa.
Comenzar ahora: Decida la arquitectura de autenticación deseada y elija su punto de entrada – elegir punto de entrada: https://affilentra.de
Si tiene preguntas sobre la configuración concreta en su infraestructura, Affilentra ofrece soporte técnico de integración para instalaciones self‑hosted.
Siguiente paso
Probar Affilentra por usted mismo
Plataforma unificada que reúne de forma transparente la provisión de productos, el tracking, la validación de conversiones, el cálculo de comisiones y los pagos con roles claramente separados; opción de instalación self-hosted con licencia perpetua sin participación en ingresos; los comerciantes mantienen el control sobre productos, condiciones y materiales promocionales; los socios reciben enlaces de tracking personales y un historial de pagos verificable.