Configuration SSO avec authentification SAML

Aperçu

Fess prend en charge l’authentification Single Sign-On (SSO) utilisant SAML (Security Assertion Markup Language) 2.0. En utilisant l’authentification SAML, les informations utilisateur authentifiées par un IdP (Identity Provider) peuvent être intégrées à Fess, permettant l’affichage de résultats de recherche basés sur les permissions utilisateur lorsqu’elle est combinée avec la recherche basée sur les rôles.

Fonctionnement de l’authentification SAML

Dans l’authentification SAML, Fess fonctionne comme un SP (Service Provider) et collabore avec un IdP externe pour l’authentification.

  1. L’utilisateur accède au point d’accès SSO de Fess (/sso/)

  2. Fess redirige la demande d’authentification vers l’IdP

  3. L’utilisateur s’authentifie auprès de l’IdP

  4. L’IdP envoie l’assertion SAML à Fess

  5. Fess valide l’assertion et connecte l’utilisateur

Pour l’intégration avec la recherche basée sur les rôles, voir Configuration de la recherche basée sur les rôles.

Prérequis

Avant de configurer l’authentification SAML, vérifiez les prérequis suivants :

  • Fess 15.7 ou supérieur est installé

  • Un IdP (Identity Provider) compatible SAML 2.0 est disponible

  • Fess est accessible via HTTPS (requis pour les environnements de production)

  • Vous avez la permission d’enregistrer Fess comme SP côté IdP

Exemples d’IdP pris en charge :

  • Microsoft Entra ID (Azure AD)

  • Okta

  • Google Workspace

  • Keycloak

  • OneLogin

  • Autres IdP compatibles SAML 2.0

Configuration de base

Activation du SSO

Pour activer l’authentification SAML, ajoutez le paramètre suivant dans app/WEB-INF/conf/system.properties :

sso.type=saml

Note

sso.type ainsi que les paramètres SAML de base (informations IdP, informations SP, mappage des attributs utilisateur) peuvent également être configurés depuis la page « Système > Général » de l’interface d’administration. Les paramètres modifiés dans l’interface d’administration sont enregistrés dans system.properties et persistent après redémarrage. Cependant, les paramètres de sécurité tels que la signature/le chiffrement ainsi que le certificat SP et la clé privée ne peuvent pas être configurés dans l’interface d’administration ; écrivez-les directement dans system.properties.

Configuration du SP (Service Provider)

Pour configurer Fess comme SP, spécifiez l’URL de base du SP.

Propriété Description Par défaut
saml.sp.base.url URL de base du SP http://localhost:8080

Note

La valeur par défaut de saml.sp.base.url est http://localhost:8080. En dehors des environnements de test, définissez toujours l’URL utilisée pour accéder à Fess depuis l’extérieur (HTTPS en production).

Ce paramètre configure automatiquement les points d’accès suivants :

  • Entity ID : {saml.sp.base.url}/sso/metadata

  • ACS URL : {saml.sp.base.url}/sso/

  • SLO URL : {saml.sp.base.url}/sso/logout

Exemple

saml.sp.base.url=https://fess.example.com

Configuration d’URL individuelle

En principe, la configuration de saml.sp.base.url permet de configurer automatiquement chaque URL de point d’accès, mais vous pouvez si nécessaire surcharger les URL individuelles explicitement avec les propriétés suivantes.

Propriété Description Par défaut
saml.sp.entityid Entity ID du SP {saml.sp.base.url}/sso/metadata
saml.sp.assertion_consumer_service.url URL du service Assertion Consumer {saml.sp.base.url}/sso/
saml.sp.single_logout_service.url URL du service Single Logout {saml.sp.base.url}/sso/logout

Configuration de l’IdP (Identity Provider)

Configurez les informations obtenues de votre IdP.

Propriété Description Par défaut
saml.idp.entityid Entity ID de l’IdP (Requis)
saml.idp.single_sign_on_service.url URL du service SSO de l’IdP (Requis)
saml.idp.x509cert Certificat X.509 de signature de l’IdP (encodé en Base64, sans sauts de ligne) (Requis)
saml.idp.single_logout_service.url URL du service SLO de l’IdP (Optionnel)

Note

Pour saml.idp.x509cert, spécifiez uniquement le contenu encodé en Base64 du certificat sur une seule ligne sans sauts de ligne. N’incluez pas les lignes -----BEGIN CERTIFICATE----- et -----END CERTIFICATE-----.

Récupération des métadonnées SP

Après le démarrage de Fess, vous pouvez récupérer les métadonnées SP au format XML depuis le point d’accès /sso/metadata.

https://fess.example.com/sso/metadata

Importez ces métadonnées dans votre IdP, ou enregistrez manuellement le SP côté IdP en utilisant le contenu des métadonnées.

Note

Pour récupérer les métadonnées, vous devez d’abord compléter la configuration SAML de base (sso.type=saml et saml.sp.base.url) et démarrer Fess.

Configuration côté IdP

Lors de l’enregistrement de Fess comme SP côté IdP, configurez les informations suivantes :

Paramètre Valeur
ACS URL / Reply URL https://<Hôte Fess>/sso/
Entity ID / Audience URI https://<Hôte Fess>/sso/metadata
Name ID Format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress (Recommandé)

Informations à obtenir de l’IdP

Obtenez les informations suivantes depuis l’écran de configuration ou les métadonnées de votre IdP pour la configuration de Fess :

  • Entity ID de l’IdP : URI identifiant l’IdP

  • URL SSO (HTTP-Redirect) : URL du point d’accès Single Sign-On

  • Certificat X.509 : Certificat de clé publique utilisé pour la vérification de signature de l’assertion SAML

Mappage des attributs utilisateur

Vous pouvez mapper les attributs utilisateur obtenus des assertions SAML aux groupes et rôles Fess.

Configuration des attributs de groupe

Propriété Description Par défaut
saml.attribute.group.name Nom de l’attribut contenant les informations de groupe memberOf
saml.default.groups Groupes par défaut (séparés par des virgules) (Aucun)

Exemple

saml.attribute.group.name=groups
saml.default.groups=user

Configuration des attributs de rôle

Propriété Description Par défaut
saml.attribute.role.name Nom de l’attribut contenant les informations de rôle (Aucun)
saml.default.roles Rôles par défaut (séparés par des virgules) (Aucun)

Exemple

saml.attribute.role.name=roles
saml.default.roles=viewer

Note

Si les attributs ne peuvent pas être obtenus de l’IdP, les valeurs par défaut seront utilisées. Lors de l’utilisation de la recherche basée sur les rôles, configurez les groupes ou rôles appropriés.

Configuration de sécurité

Pour les environnements de production, il est recommandé d’activer les paramètres de sécurité suivants.

Paramètres de signature

Propriété Description Par défaut
saml.security.authnrequest_signed Signer les demandes d’authentification false
saml.security.want_messages_signed Exiger les signatures de messages false
saml.security.want_assertions_signed Exiger les signatures d’assertions false
saml.security.logoutrequest_signed Signer les demandes de déconnexion false
saml.security.logoutresponse_signed Signer les réponses de déconnexion false

Avertissement

Les fonctionnalités de sécurité sont désactivées par défaut. Pour les environnements de production, il est fortement recommandé de définir au moins saml.security.want_assertions_signed=true.

Paramètres de chiffrement

Propriété Description Par défaut
saml.security.want_assertions_encrypted Exiger le chiffrement des assertions false
saml.security.want_nameid_encrypted Exiger le chiffrement du NameID false

Configuration du certificat SP et de la clé privée

Lorsque le SP signe les demandes d’authentification ou les messages de déconnexion (par ex. saml.security.authnrequest_signed), ou demande le chiffrement des assertions ou du NameID (par ex. saml.security.want_assertions_encrypted), vous devez configurer la clé privée et le certificat X.509 du SP.

Propriété Description Par défaut
saml.sp.x509cert Certificat X.509 du SP (encodé en Base64, sans sauts de ligne)
saml.sp.privatekey Clé privée du SP (encodée en Base64, sans sauts de ligne)

Note

Pour saml.sp.x509cert et saml.sp.privatekey, comme pour saml.idp.x509cert, spécifiez le contenu encodé en Base64 sur une seule ligne sans sauts de ligne (n’incluez pas les lignes -----BEGIN ...----- et -----END ...-----). Lorsque vous activez la signature/le chiffrement, enregistrez également le certificat SP côté IdP. Le certificat SP est publié dans les métadonnées SP à l’adresse /sso/metadata.

Autres paramètres de sécurité

Propriété Description Par défaut
saml.strict Mode strict (effectuer une validation stricte) true
saml.security.want_xml_validation Valider le schéma XML des messages true
saml.security.signature_algorithm Algorithme de signature http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
saml.security.requested_authncontext Contexte d’authentification demandé urn:oasis:names:tc:SAML:2.0:ac:classes:Password
saml.sp.nameidformat Format du NameID urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Note

Fess utilise en interne une bibliothèque SAML (java-saml), et les propriétés commençant par saml. sont mappées aux paramètres correspondants de la bibliothèque (préfixe onelogin.saml2.). Ainsi, en plus de celles répertoriées ici, vous pouvez spécifier des paramètres détaillés dans system.properties tels que les liaisons (par ex. saml.sp.assertion_consumer_service.binding), les informations d’organisation (saml.organization.*) et les informations de contact (saml.contacts.*).

Exemples de configuration

Configuration minimale (pour les tests)

Voici un exemple de configuration minimale pour la vérification dans un environnement de test.

# Activer SSO
sso.type=saml

# Configuration SP
saml.sp.base.url=https://fess.example.com

# Configuration IdP (définir les valeurs obtenues de la console d'administration IdP)
saml.idp.entityid=https://idp.example.com/saml/metadata
saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso
saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...(certificat encodé en Base64)

# Groupes par défaut
saml.default.groups=user

Configuration recommandée (pour la production)

Voici un exemple de configuration recommandée pour les environnements de production.

# Activer SSO
sso.type=saml

# Configuration SP
saml.sp.base.url=https://fess.example.com

# Configuration IdP
saml.idp.entityid=https://idp.example.com/saml/metadata
saml.idp.single_sign_on_service.url=https://idp.example.com/saml/sso
saml.idp.single_logout_service.url=https://idp.example.com/saml/logout
saml.idp.x509cert=MIIDpDCCAoygAwIBAgI...(certificat encodé en Base64)

# Mappage des attributs utilisateur
saml.attribute.group.name=groups
saml.attribute.role.name=roles
saml.default.groups=user

# Paramètres de sécurité (recommandés pour la production)
saml.security.want_assertions_signed=true
saml.security.want_messages_signed=true

Dépannage

Problèmes courants et solutions

Impossible de retourner à Fess après l’authentification

  • Vérifiez que l’URL ACS est correctement configurée côté IdP

  • Assurez-vous que la valeur de saml.sp.base.url correspond à la configuration de l’IdP

Erreur de vérification de signature

  • Vérifiez que le certificat IdP est correctement configuré

  • Assurez-vous que le certificat n’a pas expiré

  • Le certificat doit être spécifié uniquement comme contenu encodé en Base64, sans sauts de ligne

Groupes/rôles utilisateur non reflétés

  • Vérifiez que les attributs sont correctement configurés côté IdP

  • Assurez-vous que la valeur de saml.attribute.group.name correspond au nom d’attribut envoyé par l’IdP

  • Activez le mode débogage pour inspecter le contenu de l’assertion SAML

Paramètres de débogage

Pour investiguer les problèmes, vous pouvez activer le mode débogage avec le paramètre suivant :

saml.debug=true

La configuration saml.debug=true enregistre dans le journal la raison détaillée lorsque l’authentification SAML échoue.

Vous pouvez également afficher des journaux détaillés liés à SAML en ajoutant le logger suivant dans app/WEB-INF/classes/log4j2.xml :

<Logger name="org.codelibs.fess.sso.saml" level="DEBUG"/>

Référence