Authentification SAMLv2

Modifié par Aurelie Bertrand le 2024/09/11 10:59

Annexe


Ce document décrit la mise en place d’une valve d’authentification SAMLv2 pour DigDash Enterprise.

Prérequis

  • Les acronymes utilisés par la suite sont référencés dans le lexique, à la fin de ce document.
  • Avoir configuré le serveur avec un connecteur SSL/TLS (HTTPS) (cette méthode d'authentification requiert des échanges sécurisés).
  • Disposer du dossier <Install DD>/add-ons/valve_saml2 contenant tous les fichiers nécessaires à la mise en place de la valve d’authentification SAMLv2 dans le serveur Tomcat. Le placement de ces fichiers est décrit dans ce document.
    • Le dossier apache-tomcat : transposé à <DD Install>/apache-tomcat
      • Le sous-dossier lib : librairies et fichier de configuration des logs à placer dans <DD Install>/apache-tomcat/lib
      • Le sous-dossier webapps : ACS dans un .war à placer dans <DD Install>/apache-tomcat/webapps
    • Le dossier resources_samples : exemples de fichiers XML des métadonnées de l’IdP et de fichier .properties des paramètres de sécurité à éditer et placer à l’emplacement voulu.
    • Le dossier sp_metadata : Le fichier XML de métadonnées du SP DigDash.
  • Pour le moment, seule la déconnexion initiée par le SP (SP-Initiated SLO) est prise en charge.
  • Les manipulations suivantes sont à réaliser le serveur DigDash stoppé.
  • L’utilisateur à authentifier doit exister à la fois chez l’IdP et dans le LDAP.

Il est conseillé d’avoir au moins un utilisateur ayant les droits d’ajout d’utilisateurs dans le LDAP avant d’installer la valve SAMLv2, ceci afin d’éviter les échecs d’authentification SSO dès les premières connexions pour cause d’absence de tel utilisateur dans le LDAP.

Échanges mutuels des métadonnées du SP et de l’IdP

Les deux parties (Identity Provider et Service Provider) devront au préalable s’échanger mutuellement leurs métadonnées respectives sous la forme de fichiers XML . Ces métadonnées permettront notamment de connaître leur point d’entrée respectif et les détails des échanges sécurisés.

Configuration du serveur DigDash

Copie des librairies

Copiez les librairies ainsi que le fichier de configuration des logs du dossier <install DD>/add-ons/valve_saml2/apache-tomcat/lib dans le dossier :

<Install DD>/apache-tomcat/lib

Fichiers à copier :  

saml2-valve.jarslf4j-api-1.7.12.jar
commons-codec-1.10.jarlog4j-1.2.15.jar
commons-lang3-3.4.jarslf4j-log4j12-1.7.7.jar
commons-logging-1.2.jarxmlsec-2.0.7.jar
joda-time-2.9.4.jarlog4j.properties

Ajout de la valve d’authentification SAMLv2

Activez la valve d’authentification SAMLv2 dans le fichier server.xml situé dans le dossier :

<Install DD>/apache-tomcat/conf

Pour cela, chercher l’élément <Host ...> dans le fichier, décommenter ou y rajouter l’élément <Valve ...> ci-dessous :

<Valve className="com.onelogin.saml2.SAML2SSOValve"
      allowAddr="localhost,127.0.0.*,0:0:0:0:0:0:0:1"
      fallbackAuth="LDAP"
      idPMetadataPath="C:\idp_md.xml"
      securitySettingsPath="C:\saml2.sec.properties"
      uid="email"
      sharedPasswd="sharedPassword" ></Valve>

La valeur de l'attribut className est invariable.

Les valeurs des autres attributs (allowAddr, idPMetadataPath, ...) sont variables selon l'installation.

AttributDescription
classNameNom de la classe Java, implémentant l'interface org.apache.catalina.Valve, à utiliser comme Valve ici. Cet attribut est obligatoire, car il permet de sélectionner la Valve à utiliser. Il en existe en effet plusieurs implémentations fournies par Tomcat.
allowAddrAdresse IP du serveur.
fallbackAuthLa méthode d'authentification de repli
idPMetadataPathLe chemin absolu du fichier XML avec les métadonnées de l’IdP
securitySettingsPathLe chemin absolu du fichier .properties avec les paramètres de sécurité
uidUn des attributs renvoyés par l’IdP dans la réponse SAMLv2 pour identifier l’utilisateur qui s’authentifie. Si cet attribut n’est pas mentionné, le nameId de la réponse SAMLv2 est utilisé pour identifier l’utilisateur.
sharedPasswdLe mot de passe partagé et vérifié à l’authentification. Un hash au format SSHA512 peut être utilisé pour éviter d'écrire le mot de passe dans le fichier en clair (pour générer ce hash un outil comme pwdhash peut être utilisé sous Linux).
ldapForPathsFacultatif, il s’agit des expressions régulières des URLs dont les ressources sont autorisées à passer la valve, passant ainsi en mode d’authentification LDAP. Exemple : "http://localhost:8080/.*"
cookieTimeOut

Facultatif, il s’agit du temps (en secondes) au bout duquel le cookie SSO expirera. Vaut 1800 secondes (30 minutes) par défaut .
 Sinon, le cookie expirera après le nombre de secondes mentionné.

La mention d'une valeur négative signifie que le cookie expirera à la fermeture du navigateur.
La mention d'une valeur égale à 0 signifie que le cookie sera directement supprimé (non recommandé).

Exemple : cookieTimeOut="3600" (1 heure)

print_debugFacultatif, vaut false par défaut, sinon, ajouter print_debug="true" pour des traces plus verbeuses.

Ajout du .war correspondant à l’ACS du Service Provider

Ajoutez l’archive ddacs.war du dossier <install DD>/add-ons/valve_saml2/apache-tomcat/webapps dans le dossier :

<Install DD>/apache-tomcat/webapps

Il s’agit du point d’entrée ACS du SP accédé par l’IdP.

Ajout des contraintes de sécurité

Décommentez ou ajoutez les contraintes de sécurité au fichier web.xml situé dans le dossier :

<Install DD>/apache-tomcat/conf

<web-app ...>
    ...
       <security-role>
           <role-name>CUSTOM</role-name>
       </security-role>

       <security-constraint>
           <display-name>CUSTOM Security Constraint</display-name>

           <web-resource-collection>
               <web-resource-name>Protected Area</web-resource-name>
               <url-pattern>/*</url-pattern>
           </web-resource-collection>

           <auth-constraint>
               <role-name>CUSTOM</role-name>
           </auth-constraint>
       </security-constraint>

       <security-constraint>
           <web-resource-collection>
               <web-resource-name>Non-Protected Area</web-resource-name>
               <url-pattern>/vjdbc</url-pattern>
           </web-resource-collection>
       </security-constraint>
    ...
</web-app>

Configuration des applications

Pour cela, modifiez le fichier digdash.properties dans <install DD> ou /etc/digdash ou dans le dossier que vous auriez configuré dans setenv.bat/setenv.sh.

Configuration du Serveur (ddenterprise.war)

Dans le fichier digdash.properties :

Dans l'encadré ddenterpriseapi.war, rechercher et décommenter les lignes suivantes avec les valeurs indiquées :

ddenterpriseapi.authMethod=External

Configuration du Tableau de bord (digdash_dashboard.war)

Dans le fichier digdash.properties :

Dans l'encadré digdash_dashbord.war, rechercher et décommenter les lignes suivantes avec les valeurs indiquées :

digdash_dashboard.SERVERURL=http://localhost:8080
digdash_dashboard.DOMAIN=ddenterpriseapi
digdash_dashboard.FORCEDOMAIN=true
digdash_dashboard.FORCESERVERURL=true
digdash_dashboard.sharedPasswd=<la valeur de l'attribut sharedPasswd dans l'élément Valve>

La valeur d’exemple pour le paramètre digdash_dashboard.SERVERURL fera quasiment toujours référence à localhost, lorsque le tableau de bord et le serveur sont placés dans le même serveur Tomcat, ce qui représente quasiment 99.9 % des usages. Il faudra naturellement faire référence à l’adresse du serveur externe si ces deux éléments sont placés sur des serveurs différents.

Configuration du Studio (studio.war)

Dans le fichier digdash.properties :

Dans l'encadré studio.war, rechercher et décommenter les lignes suivantes avec les valeurs indiquées :

studio.SERVERURL=http://localhost:8080
studio.DOMAIN=ddenterpriseapi
studio.FORCEDOMAIN=true
studio.FORCESERVERURL=true
studio.PUBLICSERVERURL=<votre adresse URL publique>
studio.sharedPasswd=<la valeur de l'attribut sharedPasswd dans l'élément Valve>

Le paramètre studio.PUBLICSERVERURL est désormais optionnel dans le cadre de l'installation d'un SSO.

La valeur d’exemple pour ce paramètre fera quasiment toujours référence à localhost, lorsque le Studio et le serveur sont placés dans le même serveur Tomcat, ce qui représente quasiment 99.9 % des usages. Il faudra naturellement faire référence à l’adresse du serveur externe si ces deux éléments sont placés sur des serveurs différents.

Configuration de l’Identity Provider

L’IdP devra enregistrer DigDash en tant que SP dans sa liste de SP pour que DigDash puisse tirer profit de l’Authentification unique.
L’IdP devra notamment se servir du fichier métadonnées fournit par le SP pour sa configuration. Celui-ci mentionne entre autres choses les points d’entrées du SP DigDash (URL ACS).

Métadonnées du Service Provider

Les métadonnées du SP seront soit fournis directement et physiquement (par email, par clé USB, etc.) soit par génération via le SP. En effet, elles seront accessibles via l’URL suivante une fois la valve mise en place :

https://<adresse du serveur DigDash>:<port>/?spmetadata=display

Configuration du Service Provider

Le SP devra charger dans son application les métadonnées de l’IdP.

Métadonnées de l’Identity Provider

Placez le fichier au format XML fourni par l’IdP correspondant aux métadonnées de l’IdP dans le répertoire de votre choix.

Le chemin absolu de ce fichier devra être connu est devra être renseigné comme valeur de l’attribut idPMetadataPath de l'élément Valve dans Tomcat.

Configuration des paramètres de sécurité

Placez le fichier saml2.sec.properties du dossier <Install DD>/add-ons/valve_saml2/resources_samples correspondant aux paramètres de sécurité dans le répertoire de votre choix.

Le chemin absolu de ce fichier devra être connu est devra être renseigné comme valeur de l’attribut securitySettingsPath de l'élément Valve dans Tomcat.

Les tableaux suivants présentent les différentes propriétés pour paramétrer la sécurité :

Propriétés générales

Propriété généraleDescriptionValeurs possibles
onelogin.saml2.strictSi à true, le SP et en mode strict et rejettera tous les messages non cryptés ou non signés si le SP s’attend à ce qu’ils le soient.true,false
onelogin.saml2.debugSi à true, le mode debug sera activé.true,false

Propriétés du Service Provider

Les valeurs par défaut de ces propriétés sont automatiquement chargées. Vous pouvez décommenter certaines propriétés au besoin pour expliciter des valeurs.

Propriétés du Service Provider DescriptionValeurs possibles
onelogin.saml2.sp.entityidl'identifiant de l'entité Service Provider?spmetadata=display
onelogin.saml2.sp.assertion_consumer_service.urlPoint d'entrée du SP. Il s'agit de l'URL vers laquelle la <Response> SAML de l'IdP va être retournée.ddacs/acs
onelogin.saml2.sp.assertion_consumer_service.binding

Liaison de protocole SAML utilisé lors du retour du message <Response>. Onelogin  prend en charge pour ce point de terminaison la liaison HTTP-POST uniquement.

urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
onelogin.saml2.sp.single_logout_service.urlSpécifie où et comment le message <Logout Response> doit être retourné au demandeur, dans ce cas le SP.ddacs/slo
onelogin.saml2.sp.single_logout_service.bindingLiaison de protocole SAML utilisé lors du retour du <LogoutResponse> ou de l'envoi du message <LogoutRequest>. Onelogin prend en charge pour ce point de terminaison la liaison HTTP-Redirect uniquement.urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
onelogin.saml2.sp.nameidformatSpécifie des contraintes sur le NameID à utiliser pour représenter l'utilisateur à authentifier.urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
onelogin.saml2.sp.x509certLa clé publique (ou certificat) du Service Provider.Cf documentation Authentification SAMLv2 - Configuration
onelogin.saml2.sp.privatekeyLa clé privée du Service Provider.Cf documentation Authentification SAMLv2 - Configuration

Propriétés de sécurité

Propriétés de sécuritéDescriptionValeurs possibles
onelogin.saml2.security.nameid_encryptedIndique si le nameID du <samlp:logoutRequest> envoyé par le SP doit être crypté.true,false
onelogin.saml2.security.authnrequest_signedIndique si les messages <samlp:AuthnRequest> envoyés par ce SP sont signés. Les métadonnées indiquent cette information.true,false
onelogin.saml2.security.logoutrequest_signedIndique si les messages <samlp:logoutRequest> envoyés par ce SP sont signés.true,false
onelogin.saml2.security.logoutresponse_signedIndique si les messages <samlp:logoutResponse> envoyés par ce SP sont signés.true,false
onelogin.saml2.security.want_messages_signedIndique si les réponses doivent être signées.true,false
onelogin.saml2.security.want_assertions_signedIndique l’obligation des messages <samlp:Response>, <samlp:LogoutRequest> et <samlp:LogoutResponse> reçus par ce SP d’être signés.true,false
onelogin.saml2.security.sign_metadataIndique l’obligation des métadonnées de ce SP d’être signées.true,false
onelogin.saml2.security.want_assertions_encryptedIndique l’obligation des assertions reçues par ce SP d’être cryptés.true,false
onelogin.saml2.security.want_nameid_encryptedIndique l’obligation du nameID reçu par le SP d’être crypté.true,false
onelogin.saml2.security.requested_authncontextContexte d’authentification.urn:oasis:names:tc:SAML:2.0:ac:classes:Password
ou chaîne vide si vous ne voulez qu’aucun contexte ne soit envoyé dans la requête.
Plusieurs valeurs possibles, séparées par des virgules.
onelogin.saml2.security.requested_authncontextcomparisonActive la comparaison du contexte d’authentificationexact
onelogin.saml2.security.want_xml_validationIndique si le SP valide toutes les réponses XML reçues (Si true, la validation n’est effective que si cette propriété et la propriété ‘onelogin.saml2.strict’ valent aussi true).true,false
onelogin.saml2.security.signature_algorithmAlgorithme de hachage utilisé pour la signature.http://www.w3.org/2000/09/xmldsig#rsa-sha1
http://www.w3.org/2000/09/xmldsig#dsa-sha1
http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
http://www.w3.org/2001/04/xmldsig-more#rsa-sha384
http://www.w3.org/2001/04/xmldsig-more#rsa-sha512

Niveau de Logs

Vous pouvez personnaliser le niveau de log pour la valve d’authentification.

Par défaut, seuls les erreurs sont loguées. Si toutefois vous voulez avoir plus de détails sur le déroulé des actions et échanges entre les différentes entités, vous pouvez affecter la valeur ‘DEBUG’ au lieu de ‘ERROR’ dans le fichier log4j.properties qui a été importé dans le dossier lib de Tomcat.

log4j.logger.com.onelogin.saml2=ERROR, stdout
devient
log4j.logger.com.onelogin.saml2=DEBUG, stdout

Cohabitation SAMLv2 et LDAP DigDash (facultatif)

Cette fonctionnalité n'est disponible qu'à partir de la version patchée 2021R1_p20210924.

Il est possible de faire cohabiter l'authentification directe via l'annuaire LDAP DigDash alors que la méthode SAMLv2 est mise en place sur votre serveur DigDash.

Configuration préalable

Dans le fichier digdash.properties :

Dans l'encadré studio.war, rechercher et décommenter les lignes suivantes avec les valeurs indiquées :

studio.allowLoginForm=true

Dans l'encadré digdash_dashbord.war, rechercher et décommenter les lignes suivantes avec les valeurs indiquées :

digdash_dashboard.allowLoginForm=true

Activation du mode LDAP DigDash

Pour activer le mode d'authentification en mode LDAP DigDash, il suffit de rajouter dans l'URL le paramètre loginForm avec la valeur true.

Ainsi, s'il y a besoin de s'authentifier au tableau de bord directement à l'aide de vos identifiants LDAP DigDash alors que du SAMLv2 déjà installé, l'URL à utiliser sera de la forme : 

https://<host>:<port>/digdash_dashboard/index.html?loginForm=true

Attention : de manière générale, le paramètre loginForm ainsi que sa valeur seront à mentionner sur chaque domaine indépendemment les uns des autres (ddenterpriseapi pour le serveur, digdash_dashboard pour le tableau de bord, studio pour le studio web) pour s'authentifier via le LDAP.
Ainsi, activer le paramètre loginForm sur le tableau de bord (domaine digdash_dashbord) ne l'activera pas automatiquement sur le Studio Web (domaine studio) par exemple. 

Ré-activation du mode SAMLv2

Pour désactiver le mode LDAP DigDash et ainsi retourner à un état où c'est l'authentification SSO SAMLv2 qui est prise en compte, il suffit de mentionner le paramètre loginForm avec la valeur false.
Ainsi, s'il y a besoin de s'authentifier au tableau de bord via SAMLv2 alors qu'une authentification directe via le LDAP DigDash a précédemment eu lieu, l'URL à utiliser sera de la forme : 

https://<host>:<port>/digdash_dashboard/index.html?loginForm=false

La note d'avertissement précédente est également à prendre en compte dans ce cas.
 

Lexique

Nous appellerons dans ce document :

  • ACS : Assertion Consumer Service ou Service consommateur d’assertion
  • IdP : l’Identity Provider ou le Fournisseur d’identités
  • SLO : Single LogOut ou Déconnexion unique
  • SP : le Service Provider ou le Fournisseur de services (DigDash)
  • SSO : Single Sign On ou Authentification unique ; SAMLv2 est une méthode SSO

Références

https://www.oasis-open.org

DigDash utilise la librairie OpenSource onelogin de OneLogin Inc pour supporter la méthode d’authentification SAMLv2.

https://www.onelogin.com/

https://github.com/onelogin/java-saml