Authentification SAMLv2

Modifié par Aurelie Bertrand le 2024/09/12 10:04

Annexe

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

L'utilisation de SSO/SAML2 n'est pas recommandé dans le cas de l'intégration d'un tableau de bord dans une page web (via iframe).

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é à /etc/tomcat9/ sous Linux et C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf sous Windows
      • Le sous-dossier lib : librairies et fichier de configuration des logs à placer dans:
        • Sous Linux : /usr/share/tomcat9/lib/
        • Sous Windows : C:\Program Files\Apache Software Foundation\Tomcat 9.0\lib
      • Le sous-dossier webapps : ACS dans un .war à placer dans :
        • Sous Linux : /home/digdash/webapps/default
        • Sous Windows : E:/digdash/webapps/default
    • 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.

  • Dans le cas de l'utilisation d'un reverse proxy, vérifier la transmission des headers : le reverse proxy utilisé doit autoriser la communication des headers X-Forwarded-Proto et X-Forwarded-Host.

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 :

  • sous Linux : /usr/share/tomcat9/lib/
  • sous Windows : C:\Program Files\Apache Software Foundation\Tomcat 9.0\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 :

  • sous Linux : /etc/tomcat9/
  • sous Windows : C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf

Pour cela, cherchez l’élément <Host ...> dans le fichier, décommentez ou y rajoutez 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/.*"
excludedPathsFacultatif, il s’agit des expressions régulières des chemins dont les ressources sont autorisées à passer la valve, passant ainsi en mode d’authentification LDAP. Exemple : "/.*"
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 :

  • sous Linux : /home/digdash/webapps/default
  • sous Windows : E:/digdash/webapps/default

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 :

  • sous Linux : /etc/tomcat9/
  • sous Windows : C:\Program Files\Apache Software Foundation\Tomcat 9.0\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 (sous Linux) ou dans le dossier que vous auriez configuré.

Configuration du Serveur (ddenterprise.war)

Dans le fichier digdash.properties :

Dans l'encadré ddenterpriseapi.war, recherchez et décommentez 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, recherchez et décommentez 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, recherchez et décommentez 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 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 fourni 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 fournies 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 et devra être renseigné comme valeur de l’attribut idPMetadataPath de l'élément Valve dans Tomcat. 

Dans le cas où le fichier .xml des metadata n'est pas lu par l'IdP, les paramètres suivants doivent être valorisés comme indiqué ci-dessous :

  • id de l'entité : https://[serveur_url]/?spmetadata=display
  • reply : https://[serveur_url]/ddacs/acs

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

Configuration des Logs de la valve SAML 2

Dans le fichier server.xml (situé dans le dossier /etc/tomcat9/ sous Linux ou C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf sous Windows), à l'intérieur de la balise host, rajoutez la valve suivante pour avoir des logs :

<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
               prefix="localhost_access_log_test_header" suffix=".log"
                pattern="%h %l %u %t &quot;%r&quot; %s %b - X-Forwarded-Proto: %{X-Forwarded-Proto}i - X-Forwarded-For: %{X-Forwarded-For}i - X-Forwarded- Host : %{X-Forwarded-Host }i" ></Valve>

Dans l'exemple ci-dessus, les fichiers log commenceront par "localhost_access_log_test_header". Le préfixe peut être modifié comme souhaité.
Les logs se trouveront dans le dossier Tomcat.

Niveau de Logs

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

Par défaut, seules 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)

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, recherchez et décommentez les lignes suivantes avec les valeurs indiquées :

studio.allowLoginForm=true

Dans l'encadré digdash_dashboard.war, recherchez et décommentez 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.
 

Utilisation d'un reverse proxy

Dans le cas de l'utilisation d'un reverse proxy, la valve remote IP  doit être adaptée.

Ourvrir le fichier server.xml situé dans le dossier :

  • sous Linux : /etc/tomcat9/
  • sous Windows : C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf

Dans ce fichier, la valve remote IP est renseignée comme suit :

<Valve className="org.apache.catalina.valves.RemoteIpValve" 
                internalProxies="127\.0\.[0-1]\.1" 
                remoteIpHeader="x-forwarded-for" 
                requestAttributesEnabled="true" 
                protocolHeader="x-forwarded-proto" 
                protocolHeaderHttpsValue="https"/>

Remplacer la valeur de la propriété internalProxies par la valeur de l'IP du reverse proxy comme indiqué ci-dessous.

<Valve className="org.apache.catalina.valves.RemoteIpValve" 
                internalProxies="<IP DU REVERSE PROXY>" 
                remoteIpHeader="x-forwarded-for" 
                requestAttributesEnabled="true" 
                protocolHeader="x-forwarded-proto" 
                protocolHeaderHttpsValue="https"/>

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