Authentification OpenID Connect

Modifié par michelhc le 2020/11/20 16:06

Prérequis
Configuration du serveur DigDash
Configuration de l’OpenID Provider
Niveau de Logs
Authentification OpenID Connect côté Enterprise Studio
- Définitions du serveur et du domaine dans le fichier .jnlp
- Connexion au DigDash Enterprise Studio
Lexique
Références

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 <digdash_installation>/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é à <digdash_install>/apache-tomcat
  - Le sous-dossier lib : librairies et fichier de configuration des logs à placer dans <digdash_install>/apache-tomcat/lib
  - Le sous-dossier webapps : le point d’entrée DigDash (endpoint) dans un .war à placer dans <digdash_install>/apache-tomcat/webapps
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 donc 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

Ajouter les librairies ainsi que le fichier de configuration des logs du dossier apache-tomcat/lib dans le dossier

<digdash_installation>/apache/lib:

oidc-valve.jar	slf4j-log4j12-1.7.7.jar
slf4j-api-1.7.12.jar	log4j.properties
log4j-1.2.15.jar

Librairies du dossier apache-tomcat/lib

Ajout de la valve d’authentification OpenID Connect

Ajouter la valve d’authentification OpenID Connect dans le fichier server.xml situé dans le dossier

<digdash_installation>/apache-tomcat/conf

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

Extrait du fichier server.xml

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

Attributs	Description
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.
allowedCtxPath (facultatif)	Facultatif, vaut "/adminconsole" par défaut ; il s’agit du chemin du contexte dont les ressources sont autorisées à passer la valve, utile lorsque l’adminconsole est nommé autrement. Exemple : allowedCtxPath="/customadminconsole"
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 toujours https://<adresseIP>:<port>/digdash_oidc_endpoint/oidcendpoint
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é. 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.
httpReadTimeout (facultatif)	Timeout en millisecondes pour la lecture des données reçues de l’OP. 5000 ms (5 secondes) par défaut.

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

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

Ajouter l’archive digdash_oidc_endpoint.war du dossier apache-tomcat/webapps dans le dossier

<digdash_installation>/apache-tomcat/webapps.

Il s’agit du point d’entrée (endpoint) du RP accédé par l’OP.

Ajout des contraintes de sécurité

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

<digdash_installation>/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 et le Studio Web

Il peut être nécessaire, et il est conseillé de préciser sur quel serveur/domaine le Dashboard va s’appuyer.

Pour cela, modifier dans le fichier web.xml dans

<digdash_installation>/apache-tomcat/webapps/digdash_dashboard/WEB-INF.

Faire de même dans le fichier web.xml dans <digdash_installation>/apache-tomcat/webapps/studio/WEB-INF.

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

Pour forcer l’adresse du serveur, changer la valeur du paramètre FORCEURLSERVER à true. Mentionner 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

Les valeurs des paramètres DOMAIN, FORCEDOMAIN, SERVERURL, FORCESERVERURL sont variables 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 de DigDash. 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_avance_systeme_fr.pdf ».

Changement de la valeur du paramètre sharedPasswd

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

<digdash_installation>/apache-tomcat/webapps/digdash_dashboard/WEB-INF

ainsi que dans

<digdash_installation>/apache-tomcat/webapps/studio/WEB-INF

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

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

Extrait du fichier server.xml

La valeur du paramètre sharedPasswd est variable selon l'installation.

Modification de la méthode d'authentification

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

<digdash_installation>/apache-tomcat/webapps/ddenterpriseapi/WEB-INF.

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

<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

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 IP>:<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

log4j.logger.org.bsworks=DEBUG, stdout

Authentification OpenID Connect côté Enterprise Studio

Pour vous authentifier avec OpenID Connect 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 DigDash <digdash_installation>/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écharger et exécuter le .jnlp en vous rendant sur la page d’accueil DigDash dans la partie Enterprise Studio.

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

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

Capture : mire avec formulaire d’authentification de l’OP Google

L’utilisateur devra rentrer ses données de connexion et s’il a bien été authentifié chez l’OP 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 l’Enterprise Studio débutera son chargement pour se lancer.

Lexique

Nous appellerons dans ce document :

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

Références

https://www.oasis-open.org

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

https://www.boylesoftware.com/

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