Autenticación¶

IsardVDI soporta diferentes proveedores de autenticación. Puede haber múltiples proveedores en la misma instalación

OAuth2¶

Deberías configurar los tokens de autenticación de tu aplicación para habilitar este tipo de inicios de sesión.

BACKEND_HOST: Configúralo a tu dominio
BACKEND_AUTH_AUTOREGISTRATION: Activar auto registro

Google¶

BACKEND_AUTH_GOOGLE_ID: Configura tu ID de google.
BACKEND_AUTH_GOOGLE_SECRET: Configura tu secreto de google.

Github¶

BACKEND_AUTH_GITHUB_ID: Configura tu ID de github.
BACKEND_AUTH_GITHUB_SECRET: Configura tu secreto de github.

LDAP¶

La autenticación LDAP usa el mismo formulario que el inicio de sesión local.

Para configurar la autenticación LDAP, tenemos que configurar los siguientes parámetros: isardvdi.cfg.example

Revisaremos cada parámetro de configuración:

Parámetro	Valor por defecto	Descripción
`AUTHENTICATION_AUTHENTICATION_LDAP_ENABLED`	`false`	Si se configura a `true`, esto habilitará la autenticación LDAP
`AUTHENTICATION_AUTHENTICATION_LDAP_PROTOCOL`	`ldap`	El protocolo LDAP. Otros valores posibles son `ldaps`
`AUTHENTICATION_AUTHENTICATION_LDAP_HOST`		El servidor LDAP
`AUTHENTICATION_AUTHENTICATION_LDAP_PORT`	389	El puerto LDAP donde el servidor está escuchando
`AUTHENTICATION_AUTHENTICATION_LDAP_BIND_DN`		El DN que Isard va a usar para consultar el LDAP
`AUTHENTICATION_AUTHENTICATION_LDAP_PASSWORD`		La contraseña que Isard va a usar para consultar el LDAP
`AUTHENTICATION_AUTHENTICATION_LDAP_BASE_SEARCH`		El DN que todos los usuarios comparten (ej. `ou=people,dc=example,dc=com`)
`AUTHENTICATION_AUTHENTICATION_LDAP_FILTER`	`(&(objectClass=person)(uid=%s))`	El filtro que Isard va a usar para encontrar cada usuario. El `%s` representa el nombre de usuario que se envía a través del formulario. Más información aquí
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_UID`		El campo de la entrada LDAP que contiene el UID del usuario
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_UID`	`.*`	El filtro regex que se va a aplicar en el campo. Por defecto obtiene todo el campo
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_USERNAME`		El campo de la entrada LDAP que contiene el nombre de usuario del usuario
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_USERNAME`	`.*`	El filtro regex que se va a aplicar en el campo. Por defecto obtiene todo el campo
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_NAME`		El campo de la entrada LDAP que contiene el nombre del usuario
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_NAME`	`.*`	El filtro regex que se va a aplicar en el campo. Por defecto obtiene todo el campo
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_EMAIL`		El campo de la entrada LDAP que contiene el email del usuario
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_EMAIL`	`.*`	El filtro regex que se va a aplicar en el campo. Por defecto obtiene todo el campo
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_PHOTO`		El campo de la entrada LDAP que contiene la foto del usuario
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_PHOTO`	`.*`	El filtro regex que se va a aplicar en el campo. Por defecto obtiene todo el campo

En cuanto a los parámetros de configuración campo / regex: estos son los campos que la búsqueda LDAP responde. Por ejemplo, en algunas instalaciones, el campo para el email se llama 'mail'. Entonces, se aplica un regex a este campo, en caso de que necesitáramos filtrar dentro de un campo LDAP. Por defecto recoge todo el campo. La coincidencia del regex intenta extraer el primer grupo, pero si no hay grupo extraerá toda la coincidencia

Con esto, la autenticación LDAP va a funcionar. Sin embargo, ¡hay una característica ✨ extra ✨! Con la autenticación LDAP podemos autoregistrar los usuarios en grupos, así que no hay necesidad de usar los códigos de registro.

Autoregistro¶

Si un grupo tiene un código de registro, y el autoregistro LDAP está habilitado, el autoregistro LDAP siempre va a tomar preferencia. Para configurarlo, tenemos que configurar los siguientes parámetros de configuración: isardvdi.cfg.example

Revisaremos cada parámetro:

Parámetro	Valor por defecto	Descripción
`AUTHENTICATION_AUTHENTICATION_LDAP_AUTO_REGISTER`	`false`	Si se configura a `true`, esto habilitará el autoregistro LDAP
`AUTHENTICATION_AUTHENTICATION_LDAP_GUESS_CATEGORY`	`false`	Si se configura a `true`, Isard intentará adivinar la categoría basada en los resultados de la búsqueda, en lugar de confiar en la ID de categoría proporcionada por el formulario. Esto permite que múltiples categorías usen el mismo formulario y URL de inicio de sesión
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_CATEGORY`		El campo de la entrada LDAP que contiene la categoría del usuario
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_CATEGORY`	`.*`	El filtro regex que se va a aplicar en el campo. Por defecto obtiene todo el campo
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_GROUP`		El campo de la entrada LDAP que contiene el grupo del usuario
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_GROUP`	`.*`	El filtro regex que se va a aplicar en el campo. Por defecto obtiene todo el campo
`AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_SEARCH`		El DN que todos los grupos comparten (ej. `dc=example,dc=com`)
`AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_FILTER`	`(&(objectClass=posixGroup)(memberUid=%s))`	El filtro que Isard va a usar para encontrar cada usuario. El `%s` representa el nombre de usuario que se envía a través del formulario. Más información aquí
`AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_ADMIN_GROUPS`		Una lista separada por comas de los grupos que van a ser parte del rol `admin`
`AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_MANAGER_GROUPS`		Una lista separada por comas de los grupos que van a ser parte del rol `manager`
`AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_ADVANCED_GROUPS`		Una lista separada por comas de los grupos que van a ser parte del rol `advanced`
`AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_USER_GROUPS`		Una lista separada por comas de los grupos que van a ser parte del rol `user`
`AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_DEFAULT`	`user`	El rol por defecto que se le asignará al usuario si no coincide con un mapeo de grupo - rol. Los valores posibles son `admin`, `manager`, `advanced` y `user`

Ejemplos de configuraciones LDAP¶

LDAP con autoregistro

## LDAP
AUTHENTICATION_AUTHENTICATION_LDAP_ENABLED=true
AUTHENTICATION_AUTHENTICATION_LDAP_PROTOCOL=ldap
AUTHENTICATION_AUTHENTICATION_LDAP_HOST=ldap.example.com
#AUTHENTICATION_AUTHENTICATION_LDAP_PORT=389

### Credenciales usadas para consultar el LDAP
AUTHENTICATION_AUTHENTICATION_LDAP_BIND_DN="uid=isard,ou=users,dc=example,dc=com"
AUTHENTICATION_AUTHENTICATION_LDAP_PASSWORD=password

### Base Search es el DN que todos los usuarios comparten, ej. ou=people,dc=example,dc=com
AUTHENTICATION_AUTHENTICATION_LDAP_BASE_SEARCH=dc=example,dc=com
### Filter es el filtro actual usado para buscar usuarios. El '%s' representa el usuario que se envía a través del formulario
### Más información: https://confluence.atlassian.com/kb/how-to-write-ldap-search-filters-792496933.html
AUTHENTICATION_AUTHENTICATION_LDAP_FILTER="(&(objectClass=person)(uid=%s))"

### Estos son los campos que la búsqueda LDAP responde. Por ejemplo, en algunas instalaciones, el campo para el email se llama 'mail'
### Entonces, se aplica un regex a este campo, en caso de que necesitáramos filtrar dentro de un campo LDAP. Por defecto recoge todo el campo
AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_UID=uid
#AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_UID=.*
AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_USERNAME=uid
#AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_USERNAME=.*
AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_NAME=sn
#AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_NAME=.*
AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_EMAIL=mail
#AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_EMAIL=.*
#AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_PHOTO=
#AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_PHOTO=.*

### Auto Registrar los usuarios ldap existentes en IsardVDI
AUTHENTICATION_AUTHENTICATION_LDAP_AUTO_REGISTER=true
AUTHENTICATION_AUTHENTICATION_LDAP_GUESS_CATEGORY=true
### Estos son los campos que la búsqueda LDAP responde. Por ejemplo, en algunas instalaciones, el campo para el grupo se llama 'group'
### Entonces, se aplica un regex a este campo, en caso de que necesitáramos filtrar dentro de un campo LDAP. Por defecto recoge todo el campo
AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_CATEGORY=homeDirectory
AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_CATEGORY="/home/users.images/([^/]+)/[^/]+/[^/]+"
AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_GROUP=homeDirectory
AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_GROUP="/home/users.images/[^/]+/([^/]+)/[^/]+"
### La búsqueda base para listar todos los grupos de un usuario
AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_SEARCH=dc=example,dc=com
### Filter es el filtro actual usado para buscar todos los grupos de un usuario. El '%s' representa el usuario que se envía a través del formulario
### Más información: https://confluence.atlassian.com/kb/how-to-write-ldap-search-filters-792496933.html
AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_FILTER="(&(objectClass=posixGroup)(memberUid=%s))"
### El campo que contiene el grupo en la búsqueda AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_FILTER
AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_SEARCH_FIELD=cn
#AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_SEARCH_REGEX=.*
### Todos los usuarios que están en al menos uno de los grupos especificados aquí, serán creados en el rol admin (separados por comas)
AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_ADMIN_GROUPS=isard-admins
AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_MANAGER_GROUPS=isard-managers
AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_ADVANCED_GROUPS=profes,ofi
#AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_USER_GROUPS=ldapusers
# Este es el rol por defecto que tendrán los usuarios si no coinciden en ninguno de los grupos anteriores.
# Los valores pueden ser 'admin', 'manager', 'advanced', 'user'
AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_DEFAULT=user

SAML¶

IsardVDI soporta autenticación SAML 2.0 mediante integración con cualquier Proveedor de Identidad (IdP) SAML. La autenticación SAML permite que los usuarios inicien sesión utilizando el proveedor de identidad existente de su organización en lugar de gestionar credenciales separadas en IsardVDI.

Configuración Básica¶

Para configurar la autenticación SAML, debemos establecer los siguientes parámetros: isardvdi.cfg.example

Repasaremos cada parámetro de configuración:

Parámetro	Valor por defecto	Descripción
`AUTHENTICATION_AUTHENTICATION_SAML_ENABLED`	`false`	Si se establece en `true`, se habilitará la autenticación SAML
`AUTHENTICATION_AUTHENTICATION_SAML_METADATA_URL`		La URL para obtener los metadatos del IdP (ej. `https://idp.example.com/metadata`)
`AUTHENTICATION_AUTHENTICATION_SAML_METADATA_FILE`	`/keys/idp-metadata.xml`	Opcional: Archivo local de metadatos del IdP. Si este archivo existe, se usará en lugar de obtenerlo desde la URL. Esto permite que el servicio arranque sin acceso de red al IdP
`AUTHENTICATION_AUTHENTICATION_SAML_ENTITY_ID`		Opcional: Entity ID personalizado para el Proveedor de Servicio. Si no se configura, por defecto usa la URL de metadatos (`https://tu-dominio.com/authentication/saml/metadata`). Configura esto si tu IdP requiere un Entity ID específico (ej., `mi-app`)
`AUTHENTICATION_AUTHENTICATION_SAML_SIGNATURE_METHOD`		Opcional: Método de firma para firmar peticiones SAML AuthnRequests. Si no se configura, las peticiones NO se firmarán. Configura esto si tu IdP requiere peticiones firmadas (`AuthnRequestsSigned="true"`). Valores válidos: `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256` (recomendado), `http://www.w3.org/2000/09/xmldsig#rsa-sha1`, o `http://www.w3.org/2001/04/xmldsig-more#rsa-sha512`
`AUTHENTICATION_AUTHENTICATION_SAML_KEY_FILE`	`/keys/isardvdi.key`	La ruta al archivo de clave privada del Proveedor de Servicio
`AUTHENTICATION_AUTHENTICATION_SAML_CERT_FILE`	`/keys/isardvdi.cert`	La ruta al archivo de certificado del Proveedor de Servicio
`AUTHENTICATION_AUTHENTICATION_SAML_MAX_ISSUE_DELAY`	`90s`	El tiempo máximo entre la solicitud de inicio de sesión inicial y la respuesta
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_UID`		El nombre del atributo SAML que contiene el UID del usuario
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_UID`	`.*`	El filtro regex que se aplicará al campo UID. Por defecto obtiene todo el campo
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_USERNAME`		El nombre del atributo SAML que contiene el nombre de usuario
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_USERNAME`	`.*`	El filtro regex que se aplicará al campo de nombre de usuario. Por defecto obtiene todo el campo
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_NAME`		El nombre del atributo SAML que contiene el nombre para mostrar del usuario
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_NAME`	`.*`	El filtro regex que se aplicará al campo de nombre. Por defecto obtiene todo el campo
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_EMAIL`		El nombre del atributo SAML que contiene el email del usuario
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_EMAIL`	`.*`	El filtro regex que se aplicará al campo de email. Por defecto obtiene todo el campo
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_PHOTO`		El nombre del atributo SAML que contiene la URL de la foto del usuario
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_PHOTO`	`.*`	El filtro regex que se aplicará al campo de foto. Por defecto obtiene todo el campo
`AUTHENTICATION_AUTHENTICATION_SAML_SAVE_EMAIL`	`true`	Si se establece en `true`, el email se guardará en la base de datos

En cuanto a los parámetros de configuración field / regex: estos son los campos que contiene la aserción SAML. Por ejemplo, en algunas instalaciones, el campo para el email se llama 'mail'. Luego, se aplica un regex a este campo, en caso de que necesitemos extraer partes específicas de un valor de atributo SAML. Por defecto recoge todo el campo. La coincidencia de regex intenta extraer el primer grupo de captura, pero si no hay grupo extrae toda la coincidencia.

Configuración de Certificados¶

El Proveedor de Servicio (IsardVDI) requiere un certificado y clave privada para firmar las solicitudes SAML. Puedes:

Generar un certificado autofirmado:

openssl req -new -x509 -days 3652 -nodes -out /opt/isard/authentication/keys/isardvdi.cert -keyout /opt/isard/authentication/keys/isardvdi.key

Usar un certificado de la CA de tu organización
Dejar que IsardVDI genere un certificado autofirmado automáticamente (si los archivos no existen)

Archivo de Metadatos Local¶

IsardVDI soporta el uso de un archivo de metadatos local del IdP como respaldo. Esto es útil para: - Despliegues aislados (air-gapped) - Desarrollo/pruebas sin acceso a red - Arranque más rápido (sin latencia de red) - Resiliencia cuando el IdP no está temporalmente disponible

Para usar un archivo de metadatos local:

# Descargar metadatos del IdP a archivo local
curl -o /opt/isard/authentication/keys/idp-metadata.xml https://idp.example.com/metadata

Comportamiento: IsardVDI primero intentará cargar los metadatos desde el archivo local. Si el archivo no existe o falla al parsearse, automáticamente recurrirá a obtenerlos desde METADATA_URL.

Auto-registro¶

Si un grupo tiene un código de registro, y el auto-registro SAML está habilitado, el auto-registro SAML siempre tendrá preferencia. Para configurarlo, debemos establecer los siguientes parámetros de configuración:

Parámetro	Valor por defecto	Descripción
`AUTHENTICATION_AUTHENTICATION_SAML_AUTO_REGISTER`	`false`	Si se establece en `true`, se habilitará el auto-registro SAML
`AUTHENTICATION_AUTHENTICATION_SAML_AUTO_REGISTER_ROLES`	`[]`	Solo los usuarios con estos valores de rol serán auto-registrados (separados por comas). Vacío significa que todos los usuarios pueden registrarse
`AUTHENTICATION_AUTHENTICATION_SAML_GUESS_CATEGORY`	`false`	Si se establece en `true`, IsardVDI intentará adivinar la categoría basándose en atributos SAML, en lugar de confiar en el ID de categoría proporcionado por el formulario. Esto permite que múltiples categorías usen el mismo formulario y URL de inicio de sesión
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_CATEGORY`		El nombre del atributo SAML que contiene la categoría del usuario
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_CATEGORY`	`.*`	El filtro regex que se aplicará al campo de categoría. Por defecto obtiene todo el campo
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_GROUP`		El nombre del atributo SAML que contiene el grupo del usuario
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_GROUP`	`.*`	El filtro regex que se aplicará al campo de grupo. Por defecto obtiene todo el campo
`AUTHENTICATION_AUTHENTICATION_SAML_GROUP_DEFAULT`	`default`	El grupo por defecto que se asignará al usuario si no se detecta ningún grupo
`AUTHENTICATION_AUTHENTICATION_SAML_GUESS_ROLE`	`false`	Si se establece en `true`, IsardVDI intentará determinar el rol del usuario desde atributos SAML
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_ROLE`		El nombre del atributo SAML que contiene información de rol
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_ROLE`	`.*`	El filtro regex para extraer el valor de rol del atributo. Importante: Debe envolverse en comillas simples si usa caracteres especiales
`AUTHENTICATION_AUTHENTICATION_SAML_ROLE_ADMIN_IDS`	`[]`	Lista separada por comas de valores de rol que se mapearán al rol `admin`
`AUTHENTICATION_AUTHENTICATION_SAML_ROLE_MANAGER_IDS`	`[]`	Lista separada por comas de valores de rol que se mapearán al rol `manager`
`AUTHENTICATION_AUTHENTICATION_SAML_ROLE_ADVANCED_IDS`	`[]`	Lista separada por comas de valores de rol que se mapearán al rol `advanced`
`AUTHENTICATION_AUTHENTICATION_SAML_ROLE_USER_IDS`	`[]`	Lista separada por comas de valores de rol que se mapearán al rol `user`
`AUTHENTICATION_AUTHENTICATION_SAML_ROLE_DEFAULT`	`user`	El rol por defecto que se asignará al usuario si no coincide con ningún mapeo de rol. Los valores posibles son `admin`, `manager`, `advanced` y `user`

Importante: El auto-registro de categorías compara el valor de categoría extraído con el campo uid de la categoría en la base de datos (no los campos id o name). Al crear una categoría en la aplicación web para usuarios SAML, debe establecer el campo UID con el valor que será extraído por su REGEX_CATEGORY. Por ejemplo, si su regex extrae "departamento-a", cree una categoría con el UID establecido en "departamento-a".

Auto-creación de Grupos: A diferencia de las categorías, los grupos se crean automáticamente cuando AUTO_REGISTER=true está habilitado. Cuando un usuario SAML inicia sesión, IsardVDI extrae valores de grupo usando REGEX_GROUP y crea automáticamente cualquier grupo faltante con nombres auto-generados (ej., "saml_provider-saml_grupo-estudiante"). Si no se extraen grupos de los atributos SAML, el usuario se asigna al grupo predeterminado especificado en GROUP_DEFAULT (predeterminado: "default"). El administrador no necesita crear manualmente grupos en la aplicación web - se crean automáticamente en el primer inicio de sesión.

Single Logout (SLO)¶

Se soporta SAML Single Logout. El endpoint SLO se configura automáticamente en:

https://tu-dominio.com/authentication/saml/slo

Puedes configurar a dónde se redirigen los usuarios después del cierre de sesión:

Parámetro	Valor por defecto	Descripción
`AUTHENTICATION_AUTHENTICATION_SAML_LOGOUT_REDIRECT_URL`		URL para redirigir a los usuarios después del cierre de sesión. Si está vacío, redirige a `/`

Endpoints SAML¶

Cuando SAML está habilitado, IsardVDI expone los siguientes endpoints:

Endpoint	Ruta	Propósito
ACS	`https://tu-dominio.com/authentication/saml/acs`	Servicio Consumidor de Aserciones - recibe aserciones SAML del IdP
Metadata	`https://tu-dominio.com/authentication/saml/metadata`	Metadatos del Proveedor de Servicio para configuración del IdP
SLO	`https://tu-dominio.com/authentication/saml/slo`	Endpoint de Single Logout

Proporciona las URLs ACS y Metadata al administrador de tu IdP para completar la configuración SAML.

Ejemplo de Configuración SAML¶

Autenticación SAML básica con mapeo de atributos de usuario:

## SAML
AUTHENTICATION_AUTHENTICATION_SAML_ENABLED=true
AUTHENTICATION_AUTHENTICATION_SAML_METADATA_URL=https://idp.example.com/auth/realms/example/protocol/saml/descriptor

# Opcional: Usar archivo de metadatos local para arranque sin conexión
# curl -o /opt/isard/authentication/keys/idp-metadata.xml https://idp.example.com/auth/realms/example/protocol/saml/descriptor
#AUTHENTICATION_AUTHENTICATION_SAML_METADATA_FILE=/keys/idp-metadata.xml

# Opcional: Entity ID personalizado (si el IdP requiere un valor específico)
#AUTHENTICATION_AUTHENTICATION_SAML_ENTITY_ID=mi-app

# Opcional: Habilitar firmado de peticiones (si el IdP requiere AuthnRequestsSigned="true")
#AUTHENTICATION_AUTHENTICATION_SAML_SIGNATURE_METHOD=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

# Archivos de certificado (se generarán automáticamente si no existen)
AUTHENTICATION_AUTHENTICATION_SAML_KEY_FILE=/keys/isardvdi.key
AUTHENTICATION_AUTHENTICATION_SAML_CERT_FILE=/keys/isardvdi.cert

# Mapeo de Atributos de Usuario
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_UID=uid
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_USERNAME=uid
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_NAME=displayName
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_EMAIL=mail
AUTHENTICATION_AUTHENTICATION_SAML_SAVE_EMAIL=true

SAML con auto-registro y mapeo de roles:

## SAML
AUTHENTICATION_AUTHENTICATION_SAML_ENABLED=true
AUTHENTICATION_AUTHENTICATION_SAML_METADATA_URL=https://idp.example.com/metadata

# Opcional: Entity ID personalizado y firmado de peticiones
#AUTHENTICATION_AUTHENTICATION_SAML_ENTITY_ID=mi-app
#AUTHENTICATION_AUTHENTICATION_SAML_SIGNATURE_METHOD=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

# Atributos de Usuario
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_UID=uid
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_USERNAME=uid
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_NAME=displayName
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_EMAIL=mail

# Auto-registro
AUTHENTICATION_AUTHENTICATION_SAML_AUTO_REGISTER=true
AUTHENTICATION_AUTHENTICATION_SAML_AUTO_REGISTER_ROLES=teacher,student
AUTHENTICATION_AUTHENTICATION_SAML_GROUP_DEFAULT=default-group

# Mapeo de roles desde atributos SAML
# Ejemplo: Extraer rol de atributo como "urn:example:role:teacher:department:it"
AUTHENTICATION_AUTHENTICATION_SAML_GUESS_ROLE=true
AUTHENTICATION_AUTHENTICATION_SAML_FIELD_ROLE=eduPersonAffiliation
AUTHENTICATION_AUTHENTICATION_SAML_REGEX_ROLE='.*:role:([^:]+):.*'
AUTHENTICATION_AUTHENTICATION_SAML_ROLE_ADVANCED_IDS=teacher,staff
AUTHENTICATION_AUTHENTICATION_SAML_ROLE_USER_IDS=student
AUTHENTICATION_AUTHENTICATION_SAML_ROLE_DEFAULT=user

Resolución de Problemas¶

El servicio no arranca - error "fetch metadata": - Verifica que METADATA_URL sea accesible desde el servidor - Verifica la conectividad de red al IdP - Usa la opción METADATA_FILE para cargar metadatos desde un archivo local - Revisa los logs: docker logs isard-authentication

"No se recibieron atributos": - Confirma que el IdP está configurado para enviar atributos - Verifica que los nombres de parámetros FIELD_* coincidan con los nombres reales de atributos SAML - Habilita el registro de depuración para ver la aserción SAML en bruto

Errores de certificado: - Asegúrate de que existan los archivos de certificado y clave privada - Verifica los permisos de archivo (la clave debe ser 600, el certificado debe ser 644) - Verifica que el certificado no haya expirado - Verifica que la clave y el certificado coincidan:

openssl rsa -modulus -noout -in /opt/isard/authentication/keys/isardvdi.key | openssl md5
openssl x509 -modulus -noout -in /opt/isard/authentication/keys/isardvdi.cert | openssl md5

Los usuarios no se auto-registran: - Verifica que AUTO_REGISTER=true esté establecido - Verifica que el rol del usuario coincida con AUTO_REGISTER_ROLES (si está configurado) - Revisa los logs del servicio de autenticación para errores de registro

El regex no extrae correctamente: - Prueba los patrones regex en https://regex101.com/ - Recuerda envolver el regex en comillas simples si contiene caracteres especiales - El regex intenta extraer el primer grupo de captura (), o toda la coincidencia si no existe grupo

Errores "Solicitud no válida" o "Entity ID inválido" desde el IdP: - Verifica que el IdP esté configurado con el Entity ID correcto - Comprueba que tus metadatos SP coincidan con lo que espera el IdP:

curl -sk https://tu-dominio.com/authentication/saml/metadata | grep entityID

- Si el IdP requiere un Entity ID específico, configura AUTHENTICATION_AUTHENTICATION_SAML_ENTITY_ID - Asegúrate de que el IdP tenga las URLs ACS y SLO correctas configuradas

Errores "URI de redirección no válido": - Verifica que el IdP tenga las URIs de Redirección Válidas correctas configuradas: - https://tu-dominio.com/authentication/saml/acs - https://tu-dominio.com/authentication/saml/slo - https://tu-dominio.com/authentication/callback - Comprueba que la configuración del cliente del IdP tenga estas URLs en la lista permitida

Se requieren peticiones firmadas pero no funcionan: - Configura AUTHENTICATION_AUTHENTICATION_SAML_SIGNATURE_METHOD=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 - Asegúrate de que los archivos de certificado y clave estén correctamente configurados y coincidan - Verifica que el IdP tenga el certificado correcto en su configuración - Comprueba los logs en busca del mensaje "SAML request signing enabled"