Authentification SAMLv2
- Prérequis
- Configuration du serveur DigDash
- Configuration de l’Identity Provider
- Configuration du Service Provider
- Configuration des paramètres de sécurité
- Configuration de l’environnement Java
- Authentification SAML2 côté Enterprise Studio
- Lexique
- Références
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.
- Le dossier apache-tomcat : transposé à <DD Install>/apache-tomcat
- 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.
É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.jar | slf4j-api-1.7.12.jar |
| commons-codec-1.10.jar | log4j-1.2.15.jar |
| commons-lang3-3.4.jar | slf4j-log4j12-1.7.7.jar |
| commons-logging-1.2.jar | xmlsec-2.0.7.jar |
| joda-time-2.9.4.jar | log4j.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.
...
<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, ...)
| Attribut | Description |
| className | Nom 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. |
| allowAddr | Adresse IP du serveur. |
| idPMetadataPath | Le chemin absolu du fichier XML avec les métadonnées de l’IdP |
| securitySettingsPath | Le chemin absolu du fichier .properties avec les paramètres de sécurité |
| uid | Un 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. |
| sharedPasswd | Le mot de passe partagé et vérifié à l’authentification (voir point II.5) |
| ldapForPaths | Facultatif, 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 . Exemple : cookieTimeOut="3600" (1 heure) |
| print_debug | Facultatif, 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.
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.
...
<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
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.
...
<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
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
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).
...
<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.
...
<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
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 :
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.
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.
Le tableau suivant présente les différentes propriétés possibles pour paramétrer la sécurité :
| Propriétés | Description |
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.strict | Indique 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_encrypted | Indique si le nameID du <samlp:logoutRequest> envoyé par le SP doit être crypté. |
true false | |
| onelogin.saml2.security.authnrequest_signed | Indique 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_signed | Indique si les messages <samlp:logoutRequest> envoyés par ce SP sont signés. |
true false | |
| onelogin.saml2.security.logoutresponse_signed | Indique si les messages <samlp:logoutResponse> envoyés par ce SP sont signés. |
true false | |
| onelogin.saml2.security.want_messages_signed | Indique 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_signed | Indique 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_metadata | Indique 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_encrypted | Indique l’obligation des assertions reçues par ce SP d’être cryptés. |
true false | |
| onelogin.saml2.security.want_nameid_encrypted | Indique l’obligation du nameID reçu par le SP d’être crypté. |
true false | |
| onelogin.saml2.security.requested_authncontext | Contexte 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_authncontextcomparison | Active la comparaison du contexte d’authentification |
| 'exact' par défaut | |
| onelogin.saml2.security.want_xml_validation | Indique 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_algorithm | Algorithme 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
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/
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
...
<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.
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.
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.
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
DigDash utilise la librairie OpenSource onelogin de OneLogin Inc pour supporter la méhode d’authentification SAMLv2.