Autenticació¶

IsardVDI suporta diferents proveïdors d'autenticació. Pot haver-hi múltiples proveïdors a la mateixa instal·lació

OAuth2¶

Hauríeu de configurar els tokens d'autenticació de la vostra aplicació per habilitar aquest tipus d'inicis de sessió.

BACKEND_HOST: Configura-ho al teu domini
BACKEND_AUTH_AUTOREGISTRATION: Activar auto registre

Google¶

BACKEND_AUTH_GOOGLE_ID: Configura el teu ID de google.
BACKEND_AUTH_GOOGLE_SECRET: Configura el teu secret de google.

Github¶

BACKEND_AUTH_GITHUB_ID: Configura el teu ID de github.
BACKEND_AUTH_GITHUB_SECRET: Configura el teu secret de github.

LDAP¶

L'autenticació LDAP usa el mateix formulari que l'inici de sessió local.

Per configurar l'autenticació LDAP, hem de configurar els següents paràmetres: isardvdi.cfg.example

Revisarem cada paràmetre de configuració:

Paràmetre	Valor per defecte	Descripció
`AUTHENTICATION_AUTHENTICATION_LDAP_ENABLED`	`false`	Si es configura a `true`, això habilitarà l'autenticació LDAP
`AUTHENTICATION_AUTHENTICATION_LDAP_PROTOCOL`	`ldap`	El protocol LDAP. Altres valors possibles són `ldaps`
`AUTHENTICATION_AUTHENTICATION_LDAP_HOST`		El servidor LDAP
`AUTHENTICATION_AUTHENTICATION_LDAP_PORT`	389	El port LDAP on el servidor està escoltant
`AUTHENTICATION_AUTHENTICATION_LDAP_BIND_DN`		El DN que Isard va a usar per consultar l'LDAP
`AUTHENTICATION_AUTHENTICATION_LDAP_PASSWORD`		La contrasenya que Isard va a usar per consultar l'LDAP
`AUTHENTICATION_AUTHENTICATION_LDAP_BASE_SEARCH`		El DN que tots els usuaris comparteixen (ex. `ou=people,dc=example,dc=com`)
`AUTHENTICATION_AUTHENTICATION_LDAP_FILTER`	`(&(objectClass=person)(uid=%s))`	El filtre que Isard va a usar per trobar cada usuari. El `%s` representa el nom d'usuari que s'envia a través del formulari. Més informació aquí
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_UID`		El camp de l'entrada LDAP que conté l'UID de l'usuari
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_UID`	`.*`	El filtre regex que s'aplicarà al camp. Per defecte obté tot el camp
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_USERNAME`		El camp de l'entrada LDAP que conté el nom d'usuari de l'usuari
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_USERNAME`	`.*`	El filtre regex que s'aplicarà al camp. Per defecte obté tot el camp
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_NAME`		El camp de l'entrada LDAP que conté el nom de l'usuari
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_NAME`	`.*`	El filtre regex que s'aplicarà al camp. Per defecte obté tot el camp
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_EMAIL`		El camp de l'entrada LDAP que conté l'email de l'usuari
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_EMAIL`	`.*`	El filtre regex que s'aplicarà al camp. Per defecte obté tot el camp
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_PHOTO`		El camp de l'entrada LDAP que conté la foto de l'usuari
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_PHOTO`	`.*`	El filtre regex que s'aplicarà al camp. Per defecte obté tot el camp

Pel que fa als paràmetres de configuració camp / regex: aquests són els camps que la cerca LDAP respon. Per exemple, en algunes instal·lacions, el camp per l'email es diu 'mail'. Llavors, s'aplica un regex a aquest camp, en cas que necessitéssim filtrar dins d'un camp LDAP. Per defecte recull tot el camp. La coincidència del regex intenta extreure el primer grup, però si no hi ha grup extraurà tota la coincidència

Amb això, l'autenticació LDAP funcionarà. No obstant això, hi ha una característica ✨ extra ✨! Amb l'autenticació LDAP podem autoregistrar els usuaris en grups, així que no hi ha necessitat d'usar els codis de registre.

Autoregistre¶

Si un grup té un codi de registre, i l'autoregistre LDAP està habilitat, l'autoregistre LDAP sempre prendrà preferència. Per configurar-ho, hem de configurar els següents paràmetres de configuració: isardvdi.cfg.example

Revisarem cada paràmetre:

Paràmetre	Valor per defecte	Descripció
`AUTHENTICATION_AUTHENTICATION_LDAP_AUTO_REGISTER`	`false`	Si es configura a `true`, això habilitarà l'autoregistre LDAP
`AUTHENTICATION_AUTHENTICATION_LDAP_GUESS_CATEGORY`	`false`	Si es configura a `true`, Isard intentarà endevinar la categoria basada en els resultats de la cerca, en comptes de confiar en la ID de categoria proporcionada pel formulari. Això permet que múltiples categories utilitzin el mateix formulari i URL d'inici de sessió
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_CATEGORY`		El camp de l'entrada LDAP que conté la categoria de l'usuari
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_CATEGORY`	`.*`	El filtre regex que s'aplicarà al camp. Per defecte obté tot el camp
`AUTHENTICATION_AUTHENTICATION_LDAP_FIELD_GROUP`		El camp de l'entrada LDAP que conté el grup de l'usuari
`AUTHENTICATION_AUTHENTICATION_LDAP_REGEX_GROUP`	`.*`	El filtre regex que s'aplicarà al camp. Per defecte obté tot el camp
`AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_SEARCH`		El DN que tots els grups comparteixen (ex. `dc=example,dc=com`)
`AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_FILTER`	`(&(objectClass=posixGroup)(memberUid=%s))`	El filtre que Isard va a usar per trobar cada usuari. El `%s` representa el nom d'usuari que s'envia a través del formulari. Més informació aquí
`AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_ADMIN_GROUPS`		Una llista separada per comes dels grups que formaran part del rol `admin`
`AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_MANAGER_GROUPS`		Una llista separada per comes dels grups que formaran part del rol `manager`
`AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_ADVANCED_GROUPS`		Una llista separada per comes dels grups que formaran part del rol `advanced`
`AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_USER_GROUPS`		Una llista separada per comes dels grups que formaran part del rol `user`
`AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_DEFAULT`	`user`	El rol per defecte que s'assignarà a l'usuari si no coincideix amb un mapeig de grup-rol. Els valors possibles són `admin`, `manager`, `advanced` i `user`

Exemple LDAP configuracions¶

LDAP amb autoregistre

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

### Credencials usades per consultar l'LDAP
AUTHENTICATION_AUTHENTICATION_LDAP_BIND_DN="uid=isard,ou=users,dc=example,dc=com"
AUTHENTICATION_AUTHENTICATION_LDAP_PASSWORD=password

### Base Search és el DN que tots els usuaris comparteixen, ex. ou=people,dc=example,dc=com
AUTHENTICATION_AUTHENTICATION_LDAP_BASE_SEARCH=dc=example,dc=com
### Filter és el filtre actual usat per buscar usuaris. El '%s' representa l'usuari que s'envia a través del formulari
### Més informació: https://confluence.atlassian.com/kb/how-to-write-ldap-search-filters-792496933.html
AUTHENTICATION_AUTHENTICATION_LDAP_FILTER="(&(objectClass=person)(uid=%s))"

### Aquests són els camps que la cerca LDAP respon. Per exemple, en algunes instal·lacions, el camp per l'email es diu 'mail'
### Llavors, s'aplica un regex a aquest camp, en cas que necessitéssim filtrar dins d'un camp LDAP. Per defecte recull tot el camp
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 els usuaris ldap existents a IsardVDI
AUTHENTICATION_AUTHENTICATION_LDAP_AUTO_REGISTER=true
AUTHENTICATION_AUTHENTICATION_LDAP_GUESS_CATEGORY=true
### Aquests són els camps que la cerca LDAP respon. Per exemple, en algunes instal·lacions, el camp per al grup es diu 'group'
### Llavors, s'aplica un regex a aquest camp, en cas que necessitéssim filtrar dins d'un camp LDAP. Per defecte recull tot el camp
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 cerca base per llistar tots els grups d'un usuari
AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_SEARCH=dc=example,dc=com
### Filter és el filtre actual usat per buscar tots els grups d'un usuari. El '%s' representa l'usuari que s'envia a través del formulari
### Més informació: https://confluence.atlassian.com/kb/how-to-write-ldap-search-filters-792496933.html
AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_FILTER="(&(objectClass=posixGroup)(memberUid=%s))"
### El camp que conté el grup a la cerca AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_FILTER
AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_SEARCH_FIELD=cn
#AUTHENTICATION_AUTHENTICATION_LDAP_GROUPS_SEARCH_REGEX=.*
### Tots els usuaris que estan en almenys un dels grups especificats aquí, seran creats amb el rol admin (separats per comes)
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
# Aquest és el rol per defecte que tindran els usuaris si no coincideixen en cap dels grups anteriors.
# Els valors poden ser 'admin', 'manager', 'advanced', 'user'
AUTHENTICATION_AUTHENTICATION_LDAP_ROLE_DEFAULT=user

SAML¶

IsardVDI suporta autenticació SAML 2.0 mitjançant integració amb qualsevol Proveïdor d'Identitat (IdP) SAML. L'autenticació SAML permet que els usuaris iniciïn sessió utilitzant el proveïdor d'identitat existent de la seva organització en lloc de gestionar credencials separades a IsardVDI.

Configuració Bàsica¶

Per configurar l'autenticació SAML, hem d'establir els següents paràmetres: isardvdi.cfg.example

Revisarem cada paràmetre de configuració:

Paràmetre	Valor per defecte	Descripció
`AUTHENTICATION_AUTHENTICATION_SAML_ENABLED`	`false`	Si s'estableix a `true`, s'habilitarà l'autenticació SAML
`AUTHENTICATION_AUTHENTICATION_SAML_METADATA_URL`		L'URL per obtenir les metadades de l'IdP (ex. `https://idp.example.com/metadata`)
`AUTHENTICATION_AUTHENTICATION_SAML_METADATA_FILE`	`/keys/idp-metadata.xml`	Opcional: Fitxer local de metadades de l'IdP. Si aquest fitxer existeix, s'usarà en lloc d'obtenir-lo des de l'URL. Això permet que el servei arrenqui sense accés de xarxa a l'IdP
`AUTHENTICATION_AUTHENTICATION_SAML_ENTITY_ID`		Opcional: Entity ID personalitzat per al Proveïdor de Servei. Si no es configura, per defecte utilitza l'URL de metadades (`https://el-teu-domini.com/authentication/saml/metadata`). Configura això si el teu IdP requereix un Entity ID específic (ex., `la-meva-app`)
`AUTHENTICATION_AUTHENTICATION_SAML_SIGNATURE_METHOD`		Opcional: Mètode de signatura per signar peticions SAML AuthnRequests. Si no es configura, les peticions NO es signaran. Configura això si el teu IdP requereix peticions signades (`AuthnRequestsSigned="true"`). Valors vàlids: `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256` (recomanat), `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 fitxer de clau privada del Proveïdor de Servei
`AUTHENTICATION_AUTHENTICATION_SAML_CERT_FILE`	`/keys/isardvdi.cert`	La ruta al fitxer de certificat del Proveïdor de Servei
`AUTHENTICATION_AUTHENTICATION_SAML_MAX_ISSUE_DELAY`	`90s`	El temps màxim entre la sol·licitud d'inici de sessió inicial i la resposta
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_UID`		El nom de l'atribut SAML que conté l'UID de l'usuari
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_UID`	`.*`	El filtre regex que s'aplicarà al camp UID. Per defecte obté tot el camp
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_USERNAME`		El nom de l'atribut SAML que conté el nom d'usuari
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_USERNAME`	`.*`	El filtre regex que s'aplicarà al camp de nom d'usuari. Per defecte obté tot el camp
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_NAME`		El nom de l'atribut SAML que conté el nom per mostrar de l'usuari
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_NAME`	`.*`	El filtre regex que s'aplicarà al camp de nom. Per defecte obté tot el camp
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_EMAIL`		El nom de l'atribut SAML que conté l'email de l'usuari
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_EMAIL`	`.*`	El filtre regex que s'aplicarà al camp d'email. Per defecte obté tot el camp
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_PHOTO`		El nom de l'atribut SAML que conté l'URL de la foto de l'usuari
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_PHOTO`	`.*`	El filtre regex que s'aplicarà al camp de foto. Per defecte obté tot el camp
`AUTHENTICATION_AUTHENTICATION_SAML_SAVE_EMAIL`	`true`	Si s'estableix a `true`, l'email es desarà a la base de dades

Pel que fa als paràmetres de configuració field / regex: aquests són els camps que conté l'asserció SAML. Per exemple, en algunes instal·lacions, el camp per l'email s'anomena 'mail'. Després, s'aplica un regex a aquest camp, en cas que necessitem extreure parts específiques d'un valor d'atribut SAML. Per defecte recull tot el camp. La coincidència de regex intenta extreure el primer grup de captura, però si no hi ha grup extreu tota la coincidència.

Configuració de Certificats¶

El Proveïdor de Servei (IsardVDI) requereix un certificat i clau privada per signar les sol·licituds SAML. Pots:

Generar un certificat autosignat:

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

Usar un certificat de la CA de la teva organització
Deixar que IsardVDI generi un certificat autosignat automàticament (si els fitxers no existeixen)

Fitxer de Metadades Local¶

IsardVDI suporta l'ús d'un fitxer de metadades local de l'IdP com a recolzament. Això és útil per: - Desplegaments aïllats (air-gapped) - Desenvolupament/proves sense accés a xarxa - Arrencada més ràpida (sense latència de xarxa) - Resiliència quan l'IdP no està temporalment disponible

Per usar un fitxer de metadades local:

# Descarregar metadades de l'IdP a fitxer local
curl -o /opt/isard/authentication/keys/idp-metadata.xml https://idp.example.com/metadata

Comportament: IsardVDI primer intentarà carregar les metadades des del fitxer local. Si el fitxer no existeix o falla en analitzar-se, automàticament recorrerà a obtenir-les des de METADATA_URL.

Auto-registre¶

Si un grup té un codi de registre, i l'auto-registre SAML està habilitat, l'auto-registre SAML sempre tindrà preferència. Per configurar-lo, hem d'establir els següents paràmetres de configuració:

Paràmetre	Valor per defecte	Descripció
`AUTHENTICATION_AUTHENTICATION_SAML_AUTO_REGISTER`	`false`	Si s'estableix a `true`, s'habilitarà l'auto-registre SAML
`AUTHENTICATION_AUTHENTICATION_SAML_AUTO_REGISTER_ROLES`	`[]`	Només els usuaris amb aquests valors de rol seran auto-registrats (separats per comes). Buit significa que tots els usuaris poden registrar-se
`AUTHENTICATION_AUTHENTICATION_SAML_GUESS_CATEGORY`	`false`	Si s'estableix a `true`, IsardVDI intentarà endevinar la categoria basant-se en atributs SAML, en lloc de confiar en l'ID de categoria proporcionat pel formulari. Això permet que múltiples categories usin el mateix formulari i URL d'inici de sessió
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_CATEGORY`		El nom de l'atribut SAML que conté la categoria de l'usuari
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_CATEGORY`	`.*`	El filtre regex que s'aplicarà al camp de categoria. Per defecte obté tot el camp
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_GROUP`		El nom de l'atribut SAML que conté el grup de l'usuari
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_GROUP`	`.*`	El filtre regex que s'aplicarà al camp de grup. Per defecte obté tot el camp
`AUTHENTICATION_AUTHENTICATION_SAML_GROUP_DEFAULT`	`default`	El grup per defecte que s'assignarà a l'usuari si no es detecta cap grup
`AUTHENTICATION_AUTHENTICATION_SAML_GUESS_ROLE`	`false`	Si s'estableix a `true`, IsardVDI intentarà determinar el rol de l'usuari des d'atributs SAML
`AUTHENTICATION_AUTHENTICATION_SAML_FIELD_ROLE`		El nom de l'atribut SAML que conté informació de rol
`AUTHENTICATION_AUTHENTICATION_SAML_REGEX_ROLE`	`.*`	El filtre regex per extreure el valor de rol de l'atribut. Important: Ha d'envoltar-se en cometes simples si usa caràcters especials
`AUTHENTICATION_AUTHENTICATION_SAML_ROLE_ADMIN_IDS`	`[]`	Llista separada per comes de valors de rol que es mapejaran al rol `admin`
`AUTHENTICATION_AUTHENTICATION_SAML_ROLE_MANAGER_IDS`	`[]`	Llista separada per comes de valors de rol que es mapejaran al rol `manager`
`AUTHENTICATION_AUTHENTICATION_SAML_ROLE_ADVANCED_IDS`	`[]`	Llista separada per comes de valors de rol que es mapejaran al rol `advanced`
`AUTHENTICATION_AUTHENTICATION_SAML_ROLE_USER_IDS`	`[]`	Llista separada per comes de valors de rol que es mapejaran al rol `user`
`AUTHENTICATION_AUTHENTICATION_SAML_ROLE_DEFAULT`	`user`	El rol per defecte que s'assignarà a l'usuari si no coincideix amb cap mapatge de rol. Els valors possibles són `admin`, `manager`, `advanced` i `user`

Important: L'auto-registre de categories compara el valor de categoria extret amb el camp uid de la categoria a la base de dades (no els camps id o name). En crear una categoria a l'aplicació web per usuaris SAML, heu d'establir el camp UID amb el valor que serà extret pel vostre REGEX_CATEGORY. Per exemple, si el vostre regex extreu "departament-a", creeu una categoria amb el UID establert a "departament-a".

Auto-creació de Grups: A diferència de les categories, els grups es creen automàticament quan AUTO_REGISTER=true està habilitat. Quan un usuari SAML inicia sessió, IsardVDI extreu valors de grup usant REGEX_GROUP i crea automàticament qualsevol grup que falti amb noms auto-generats (ex., "saml_provider-saml_grup-estudiant"). Si no s'extreuen grups dels atributs SAML, l'usuari s'assigna al grup predeterminat especificat a GROUP_DEFAULT (predeterminat: "default"). L'administrador no necessita crear manualment grups a l'aplicació web - es creen automàticament en el primer inici de sessió.

Single Logout (SLO)¶

Es suporta SAML Single Logout. L'endpoint SLO es configura automàticament a:

https://el-teu-domini.com/authentication/saml/slo

Pots configurar on es redirigeixen els usuaris després del tancament de sessió:

Paràmetre	Valor per defecte	Descripció
`AUTHENTICATION_AUTHENTICATION_SAML_LOGOUT_REDIRECT_URL`		URL per redirigir els usuaris després del tancament de sessió. Si està buit, redirigeix a `/`

Endpoints SAML¶

Quan SAML està habilitat, IsardVDI exposa els següents endpoints:

Endpoint	Ruta	Propòsit
ACS	`https://el-teu-domini.com/authentication/saml/acs`	Servei Consumidor d'Assercions - rep assercions SAML de l'IdP
Metadata	`https://el-teu-domini.com/authentication/saml/metadata`	Metadades del Proveïdor de Servei per configuració de l'IdP
SLO	`https://el-teu-domini.com/authentication/saml/slo`	Endpoint de Single Logout

Proporciona les URLs ACS i Metadata a l'administrador del teu IdP per completar la configuració SAML.

Exemple de Configuració SAML¶

Autenticació SAML bàsica amb mapatge d'atributs d'usuari:

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

# Opcional: Usar fitxer de metadades local per arrencada sense connexió
# 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 personalitzat (si l'IdP requereix un valor específic)
#AUTHENTICATION_AUTHENTICATION_SAML_ENTITY_ID=la-meva-app

# Opcional: Habilitar signat de peticions (si l'IdP requereix AuthnRequestsSigned="true")
#AUTHENTICATION_AUTHENTICATION_SAML_SIGNATURE_METHOD=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

# Fitxers de certificat (es generaran automàticament si no existeixen)
AUTHENTICATION_AUTHENTICATION_SAML_KEY_FILE=/keys/isardvdi.key
AUTHENTICATION_AUTHENTICATION_SAML_CERT_FILE=/keys/isardvdi.cert

# Mapatge d'Atributs d'Usuari
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 amb auto-registre i mapatge de rols:

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

# Opcional: Entity ID personalitzat i signat de peticions
#AUTHENTICATION_AUTHENTICATION_SAML_ENTITY_ID=la-meva-app
#AUTHENTICATION_AUTHENTICATION_SAML_SIGNATURE_METHOD=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

# Atributs d'Usuari
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-registre
AUTHENTICATION_AUTHENTICATION_SAML_AUTO_REGISTER=true
AUTHENTICATION_AUTHENTICATION_SAML_AUTO_REGISTER_ROLES=teacher,student
AUTHENTICATION_AUTHENTICATION_SAML_GROUP_DEFAULT=default-group

# Mapatge de rols des d'atributs SAML
# Exemple: Extreure rol d'atribut com "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ó de Problemes¶

El servei no arrenca - error "fetch metadata": - Verifica que METADATA_URL sigui accessible des del servidor - Verifica la connectivitat de xarxa a l'IdP - Usa l'opció METADATA_FILE per carregar metadades des d'un fitxer local - Revisa els logs: docker logs isard-authentication

"No s'han rebut atributs": - Confirma que l'IdP està configurat per enviar atributs - Verifica que els noms de paràmetres FIELD_* coincideixin amb els noms reals d'atributs SAML - Habilita el registre de depuració per veure l'asserció SAML en cru

Errors de certificat: - Assegura't que existeixin els fitxers de certificat i clau privada - Verifica els permisos de fitxer (la clau ha de ser 600, el certificat ha de ser 644) - Verifica que el certificat no hagi expirat - Verifica que la clau i el certificat coincideixin:

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

Els usuaris no s'auto-registren: - Verifica que AUTO_REGISTER=true estigui establert - Verifica que el rol de l'usuari coincideixi amb AUTO_REGISTER_ROLES (si està configurat) - Revisa els logs del servei d'autenticació per errors de registre

El regex no extreu correctament: - Prova els patrons regex a https://regex101.com/ - Recorda embolicar el regex en cometes simples si conté caràcters especials - El regex intenta extreure el primer grup de captura (), o tota la coincidència si no existeix grup

Errors "Sol·licitud no vàlida" o "Entity ID invàlid" des de l'IdP: - Verifica que l'IdP estigui configurat amb l'Entity ID correcte - Comprova que les teves metadades SP coincideixin amb el que espera l'IdP:

curl -sk https://el-teu-domini.com/authentication/saml/metadata | grep entityID

- Si l'IdP requereix un Entity ID específic, configura AUTHENTICATION_AUTHENTICATION_SAML_ENTITY_ID - Assegura't que l'IdP tingui les URLs ACS i SLO correctes configurades

Errors "URI de redirecció no vàlid": - Verifica que l'IdP tingui les URIs de Redirecció Vàlides correctes configurades: - https://el-teu-domini.com/authentication/saml/acs - https://el-teu-domini.com/authentication/saml/slo - https://el-teu-domini.com/authentication/callback - Comprova que la configuració del client de l'IdP tingui aquestes URLs a la llista permesa

Es requereixen peticions signades però no funcionen: - Configura AUTHENTICATION_AUTHENTICATION_SAML_SIGNATURE_METHOD=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 - Assegura't que els fitxers de certificat i clau estiguin correctament configurats i coincideixin - Verifica que l'IdP tingui el certificat correcte a la seva configuració - Comprova els logs en cerca del missatge "SAML request signing enabled"