Authentification SAMLv2

Modifié par jhurst le 2021/10/08 08:11

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 <DD Install>/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

Ajoutez les librairies ainsi que le fichier de configuration des logs du dossier <DD Install>/apache-tomcat/lib dans le dossier

<DD Install>/apache/lib:

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

Librairies du dossier apache-tomcat/lib

Ajout de la valve d’authentification SAMLv2

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

<DD Install>/apache-tomcat/conf

Pour cela, ajoutez l’élément Valve suivant dans l’élément Host.

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

Extrait du fichier server.xml

Valeur invariable (className) 

Valeur variable selon l’installation (allowAddr, idPMetadataPath, ...)

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.
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 (voir point II.5)
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é.

Exemple : cookieTimeOut="3600" (1 heure)

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

Tableau décrivant les attributs de l’élément Valve

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

Ajoutez l’archive ddacs.war du dossier apache-tomcat/webapps dans le dossier

<DD Install>/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é

Ajoutez les contraintes de sécurité au fichier web.xml situé dans le dossier

<DD Install>/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>

Extrait du fichier web.xml

URL du serveur et domaine pour le Dashboard

Il est fortement conseillé de préciser sur quel serveur/domaine le Dashboard va s’appuyer.

Pour cela, modifiez dans le fichier web.xml dans

<DD Install>/apache-tomcat/webapps/digdash_dashboard/WEB-INF.

Pour forcer le domaine, changez la valeur du paramètre FORCEDOMAIN à true.
Mentionnez le nom du domaine en changeant le paramètre DOMAIN.

Pour forcer l’adresse du serveur, changer la valeur du paramètre FORCESERVERURL à true. Mentionnez l’adresse du serveur en changeant le paramètre SERVERURL.

<web-app ...>
    ...
       <servlet>
           <servlet-name>dashServlet</servlet-name>
           <servlet-class>com.digdash.server.DigdashServiceImpl</servlet-class>
        ...
           <init-param>
               <param-name>DOMAIN</param-name>
               <param-value>ddenterpriseapi</param-value>
           </init-param>

           <init-param>
               <param-name>FORCEDOMAIN</param-name>
               <param-value>true</param-value>
           </init-param>

           <init-param>
               <param-name>SERVERURL</param-name>
               <param-value>http://localhost:8080</param-value>
           </init-param>

           <init-param>
               <param-name>FORCESERVERURL</param-name>
               <param-value>true</param-value>
           </init-param>
            ...
       </servlet>
    ...
</web-app>

Extrait du fichier web.xml

Valeur variable selon l’installation

La valeur d’exemple pour le paramètre 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 % 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.

Ce paramètre est éditable via le fichier web.xml comme indiqué ci-dessus. Ce fichier est propre à chaque installation. Il vous est possible de renseigner ce paramètre de manière plus globale dans le fichier.

<utilisateur>/Application Data/Enterprise Server/dashboard_system.xml 

Pour en savoir plus, vous pouvez vous référer à la documentation DigDash « Guide avancé système »

Changement de la valeur du paramètre sharedPasswd

Changez la valeur du paramètre sharedPasswd (valeur secret ci-dessous à changer) dans le fichier web.xml de Dashboard dans le dossier

<DD Install>/apache-tomcat/webapps/digdash_dashboard/WEB-INF.

La valeur doit correspondre à celle mentionnée dans l’attribut sharedPasswd dans la valve du fichier

<DD Install>/apache-tomcat/conf/server.xml (voir partie II.2).

<web-app ...>
    ...
       <servlet>
           <servlet-name>dashServlet</servlet-name>
           <servlet-class>com.digdash.server.DigdashServiceImpl</servlet-class>
        ...

           <init-param>
               <param-name>sharedPasswd</param-name>
               <param-value>secret</param-value>
           </init-param>
            ...
       </servlet>
    ...
 </web-app>

Extrait du fichier server.xml

Modification de la méthode d'authentification

Modifiez la méthode d'authentification (LDAP est la méthode par défaut) dans le fichier web.xml situé dans le dossier :

<DD Install>/apache-tomcat/webapps/ddenterpriseapi/WEB-INF.

<web-app ...>
    ...
       <servlet>
            ...
       </servlet>
    ...
       <servlet>
           <description></description>
           <display-name>DDEnterpriseAuthServlet</display-name>
           <servlet-name>DDEnterpriseAuthServlet</servlet-name>
           <servlet-class>com.digdash.server.DDEnterpriseAuthServlet</servlet-class>

               <init-param>
                   <param-name>authMethod</param-name>
                   <param-value>External</param-value>
               </init-param>
                ...
       </servlet>
    ...
 </web-app>

Extrait du fichier web.xml

"External" signifie que la sécurité est gérée par la valve configurée ci-dessus.

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.

NB : Le chemin absolu de ce fichier sera connu est sera renseigné comme valeur de l’attribut idPMetadataPath de la valve SAMLv2 (voir partie II.2).

Configuration des paramètres de sécurité

Placez le fichier au format .properties correspondant aux paramètres de sécurité dans le répertoire de votre choix.

NB : Le chemin absolu de ce fichier sera connu est sera renseigné comme valeur de l’attribut securitySettingsPath de la valve SAMLv2 (voir partie II.2).

Le tableau suivant présente les différentes propriétés possibles pour paramétrer la sécurité :

PropriétésDescription

onelogin.saml2.sp.entityid

onelogin.saml2.sp.assertion_consumer_service.url

onelogin.saml2.sp.assertion_consumer_service.binding

onelogin.saml2.sp.single_logout_service.url

onelogin.saml2.sp.single_logout_service.binding

onelogin.saml2.sp.nameidformat

onelogin.saml2.sp.x509cert

onelogin.saml2.sp.privatekey

Propriétés relatives au Service Provider.

Les valeurs par défaut de ces propriétés sont automatiquement chargées côté SP.

Si besoin, il est possible de surcharger ces propriétés en les mentionnant dans le fichier properties.

La description plus détaillée de ces paramètres ainsi que les valeurs utilisées sont directement consultables dans le fichier de sécurité resources_samples\saml2.sec.properties fourni.

onelogin.saml2.strictIndique si le SP rejette tous les messages non cryptés ou non signés si le SP s’attend à ce qu’ils le soient.

true

false

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 Le message est requis d’être signé

false Le message n’est pas requis d’être signé

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 requiert la signature des métadonnées

false par défaut

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

Vide si vous ne voulez qu’aucun contexte ne soit envoyé dans la requête AuthnRequest

Plusieurs valeurs séparées par des virgules sinon.

onelogin.saml2.security.onelogin.saml2.security.requested_authncontextcomparisonActive la comparaison du contexte d’authentification
'exact' par défaut
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

Tableau décrivant les paramètres de sécurité possible

Les champs grisés sont des champs proposés par la librairie onelogin mais qui ne sont pas encore mis en œuvre pour la valve SAMLv2 de DigDash donc non pris en compte.

Configuration de l’environnement Java

L'extension JCE (Java Cryptography Extension) est requise. Vous pouvez télécharger la version jce-6, jce-7 ou jce-8,  décompressez là dans le dossier suivant

${java.home}/jre/lib/security/

VersionsLiens de téléchargement
jce-6http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html
jce-7http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html
jce-8http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html

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

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

Authentification SAML2 côté Enterprise Studio

Pour vous authentifier avec SAMLv2 côté Enterprise Studio, veuillez vous assurer d’avoir réalisé les actions suivantes 

Définitions du serveur et du domaine dans le fichier .jnlp

Vous pouvez, à l’instar du Dashboard, définir le serveur et le domaine sur lequel DigDash va s’appuyer.

Pour ce faire, modifier la fin du fichier digdash.jnlp dans le dossier d’installation <DD Install>/apache-tomcat/webapps/adminconsole

<jnlp ...>

...

<application-desc main-class="commandline.CommandLineMain">

<argument>https://localhost:8443</argument> (1)

<argument>ddenterpriseapi</argument> (2)

<argument><%=lang%></argument> (3)

<argument><%=dashboard%></argument> (4)

<argument>-AuthMode=External</argument> (5)

<argument>-SSLNoPathCheck</argument> (A)

...

</application-desc>

</jnlp>

Extrait du fichier digdash.jnlp

Attention : les arguments notées (1), (2), (3), (4), (5) ne doivent pas changer d’ordre.

Argument (1) : l’adresse du serveur DigDash ; variable selon votre installation

Argument (2) : le nom du domaine DigDash ; variable selon votre installation

Argument (5) : La méthode d’authentification ; External, obligatoirement

Argument (A) : argument facultatif, parfois nécessaire dans les cas de connexions SSL, HTTPS.

Connexion au DigDash Enterprise Studio

Téléchargez et exécutez le .jnlp en vous rendant sur la page d’accueil dans la partie Enterprise Studio.

1599032022621-355.png

Une fenêtre d’authentification doit apparaître avec la mire d’authentification de l’IdP.

Dans ce document, Salesforce est l’IdP que nous avons choisi pour illustrer nos exemples.

config_auth_saml2_fr_test_html_dff5c9e389ba1c1d.png

Capture : mire avec formulaire d’authentification de l’IdP Salesforce

L’utilisateur devra rentrer ses données de connexion et s’il a bien été authentifié chez l’IdP et qu’il correspond bien à un utilisateur existant dans le LDAP DigDash, l’authentification aura réussi et la fenêtre attestera du succès de l’authentification.

config_auth_saml2_fr_test_html_6230a5f637fd4c54.png

Capture : fenêtre d’une authentification réussie

La fenêtre se fermera automatiquement, puis le Studio débutera son chargement pour se lancer.

Lexique

Nous appellerons dans ce document :

SSO : Single Sign On ou Authentification unique ; SAMLv2 est une méthode SSO

SLO : Single LogOut ou Déconnexion unique

IdP : l’Identity Provider ou le Fournisseur d’identités

SP : le Service Provider ou le Fournisseur de services (DigDash)

ACS : Assertion Consumer Service ou Service consommateur d’assertion

Références

https://www.oasis-open.org

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

https://www.onelogin.com/

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