Authentification OpenID Connect

Modifié par Aurelie Bertrand le 2024/05/22 10:11

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

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 DigDash 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_openidconnect contenant tous les fichiers nécessaires à la mise en place de la valve d’authentification OpenID Connect dans le serveur Tomcat de DigDash. 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 : le point d’entrée DigDash (endpoint) dans un .war à placer dans:
        • sous Linux : /home/digdash/webapps/default
        • sous Windows : E:/digdash/webapps/default
  • Les manipulations suivantes sont à réaliser le serveur DigDash stoppé.
  • L’utilisateur à authentifier doit exister à la fois chez l’OP et dans le LDAP DigDash.

Il est conseillé d’avoir au moins un utilisateur ayant les droits d’ajout d’utilisateurs DigDash dans le LDAP DigDash avant d’installer la valve OpenID Connect, 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.

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_openidconnect/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 : 

oidc-valve.jarlog4j-api-2.19.0.jar
slf4j-api-2.0.6.jarlog4j-1.2-api-2.19.0.jar
log4j-slf4j-impl-2.19.0.jarlog4j2.properties
log4j-core-2.19.0.jar 

Ajout de la valve d’authentification OpenID Connect

Activez la valve d’authentification OpenID Connect 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="org.bsworks.catalina.authenticator.oidc.OpenIDConnectSSOValve"
allowAddr="localhost,127.0.0.*,0:0:0:0:0:0:0:1"
sharedPasswd="secret"
redirect_url="https://localhost:8443/digdash_oidc_endpoint/oidcendpoint"
providers="[
                 {
                   name: OpenID Provider name,
                   issuer: issuer,
                   clientId: clientId,
                   clientSecret: clientSecret
                 }
          ]"
usernameClaim="email"
additionalScopes="email"
cookieTimeOut="-1"
          ></Valve>

La valeur de l'attribut className est invariable.
Les valeurs des attributs allowAddr, sharedPasswd, redirect_url, providers, usernameClaim, additionalScopes sont variables selon l'installation.

💡 L'attribut cookieTimeOut est facultatif et peut prendre différentes valeurs comme décrit ci-dessous.
Cependant, il est recommandé d'utiliser cookieTimeOut="-1"  .

AttributsDescription
className (obligatoire)     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 existe en effet plusieurs implémentations fournies par Tomcat.
allowAddr (obligatoire)     Adresse IP du serveur.
fallbackAuth (obligatoire)La méthode d'authentification de repli
sharedPasswd (obligatoire)     Le mot de passe partagé et vérifié à l’authentification (voir point II.5)
redirect_url (obligatoire)     

Il s'agit du chemin de l’application vers lequel les utilisateurs seront redirigés après s'être authentifiés avec l’OP. Pour DigDash, l’URL sera https://<adresse DigDash>:<port>/digdash_oidc_endpoint/oidcendpoint

ou
La valeur peut être "/digdash_oidc_endpoint/oidcendpoint" ; dans ce cas là, l'adresse DigDash sera calculée selon l'adresse courante.

cookieTimeOut (facultatif)     

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_debug (facultatif)     Facultatif, vaut false par défaut, sinon, ajouter print_debug="true" pour des traces plus verbeuses.
providers (obligatoire)     

Valeur de forme tableau d’objets en JSON. Chaque élément correspond à un OpenID Provider utilisé par l’application.

La syntaxe diffère du format standard JSON dans le sens où les doubles quotes ne sont pas utilisées pour les noms des propriétés et de leur valeur (de sorte à rendre le format plus XMLien). Une valeur peut être entourée par des simples quotes si celle-ci contient des séparateurs tels qu’une virgule, des accolades ou des espaces. Chaque objet représentant un OP comporte les propriétés suivantes :

- issuer (obligatoire) : Il s’agit d’une URL unique pour identifier l’OP.     

- name (facultatif) : Un nom associé à l’OP ; l’issuer sinon par défaut.

- clientId (obligatoire) : Le client ID associé à l’application chez l’OP.

- clientSecret (facultatif) : Le client Secret. Notez que la plupart des OPs requièrent un client Secret, notamment pour les appels aux points d’entrées de l’OP. Néanmoins, certains OPs supportent des clients publiques, d’où l’absence de client Secret.

- usernameClaim (facultatif) : L’attribut user Identifier réclamé par le RP et renvoyé par l’OP pour identifier l’utilisateur qui s’authentifie.

- additionalScopes (facultatif) : Les scopes additionnels au scope ‘openid’ séparés par des espaces.

usernameClaim (facultatif)     Le user Identifier par défaut utilisé par tous les OPs qui n’en spécifient pas un dans les propriétés propres de l’OP.
additionalScopes (facultatif)     Les scopes additionnels par défaut utilisés par tous les OPs qui n’en spécifient pas un dans les propriétés propres de l’OP.
httpConnectTimeout (facultatif)     Timeout en millisecondes pour l’établissement de la connexion vers l’OP. 5000 ms (5 secondes) par défaut.
ldapForPaths (facultatif)     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 : "https://localhost:8443/digdash_dashboard/.*"

Ajout du .war correspondant au point d’entrée du Relying Party

Ajoutez l’archive digdash_oidc_endpoint.war du dossier <install DD>/add-ons/valve_openidconnect/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 (endpoint) du RP accédé par l’OP.

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 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 en HTTPS>
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’OpenID Provider

L’OP devra enregistrer DigDash en tant que RP dans sa liste de RP pour que DigDash puisse tirer profit de l’Authentification unique.

Aussi, l’OP devra renseigner l’URL de callback pour identifier le point d’entrée de l’application DigDash. L’URL sera de la forme

https://<adresse du serveur DigDash>:<port>/digdash_oidc_endpoint/oidcendpoint

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.org.bsworks=ERROR, stdout
devient
log4j.logger.org.bsworks=DEBUG, stdout

Cohabitation OpenID Connect et LDAP DigDash (facultatif)

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

Il est possible de faire cohabiter l'authentification directe via l'annuaire LDAP DigDash alors que la méthode OpenID Connect 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_dashbord.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 OpenIDConnect est 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épendamment 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 OpenID Connect

Pour désactiver le mode LDAP DigDash et ainsi retourner à un état où c'est l'authentification SSO OpenID Connect 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 OpenID Connect 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.
 

Pour passer d'un mode d'authentification à l'autre, il est fortement conseillé de suivre l'une des règles suivantes :

  • se déconnecter de l'utilisateur courant dans le cadre d'une utilisation d'une même session navigateur
  • utiliser une session navigateur différente (soit en navigation privée sur un même navigateur ou basculer sur un navigateur différent) 

Lexique

Nous appellerons dans ce document :

  • Endpoint : Point d’entrée
  • OP : OpenID Provider ou le Fournisseur d’identités
  • RP : Relying Party ou le Fournisseur de services (DigDash)
  • SSO : Single Sign On ou Authentification unique ; OpenIDConnect est une méthode SSO

Références

https://www.oasis-open.org

DigDash utilise la librairie OpenSource tomcat8-oidcauth de Boyle Software, Inc. pour supporter la méthode d’authentification OpenID Connect.

https://www.boylesoftware.com/

https://github.com/boylesoftware/tomcat8-oidcauth