Authentification SAMLv2
- Prérequis
- Configuration du serveur DigDash
- Configuration des applications
- Configuration de l’Identity Provider
- Configuration du Service Provider
- Configuration des paramètres de sécurité
- Niveau de Logs
- Cohabitation SAMLv2 et LDAP DigDash (facultatif)
- 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 <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.
- 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
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.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 |
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 :
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.
| 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. |
| fallbackAuth | La méthode d'authentification de repli |
| 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. 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). |
| 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 . La mention d'une valeur négative signifie que le cookie expirera à la fermeture du navigateur. Exemple : cookieTimeOut="3600" (1 heure) |
| print_debug | Facultatif, 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
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
...
<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 :
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.DOMAIN=ddenterpriseapi
digdash_dashboard.FORCEDOMAIN=true
digdash_dashboard.FORCESERVERURL=true
digdash_dashboard.sharedPasswd=<la valeur de l'attribut sharedPasswd dans l'élément Valve>
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.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>
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 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.
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érale | Description | Valeurs possibles |
| onelogin.saml2.strict | Si à 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.debug | Si à true, le mode debug sera activé. | true,false |
Propriétés du Service Provider
| Propriétés du Service Provider | Description | Valeurs possibles |
| onelogin.saml2.sp.entityid | l'identifiant de l'entité Service Provider | ?spmetadata=display |
| onelogin.saml2.sp.assertion_consumer_service.url | Point 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.url | Spé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.binding | Liaison 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.nameidformat | Spé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.x509cert | La clé publique (ou certificat) du Service Provider. | Cf documentation Authentification SAMLv2 - Configuration |
| onelogin.saml2.sp.privatekey | La clé privée du Service Provider. | Cf documentation Authentification SAMLv2 - Configuration |
Propriétés de sécurité
| Propriétés de sécurité | Description | Valeurs possibles |
| 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,false |
| 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,false |
| 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. | 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_authncontextcomparison | Active la comparaison du contexte d’authentification | exact |
| 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 |
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)
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 :
Dans l'encadré digdash_dashbord.war, rechercher et décommenter les lignes suivantes avec les valeurs indiquées :
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
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
DigDash utilise la librairie OpenSource onelogin de OneLogin Inc pour supporter la méthode d’authentification SAMLv2.