Modifié par Aurelie Bertrand le 2024/04/15 09:33
Afficher les derniers auteurs
1 {{ddtoc/}}
2
3 ----
4
5 (% class="wikigeneratedid" %)
6 Ce document décrit la mise en place d’une valve d’authentification OpenID Connect pour DigDash.
7
8 = Prérequis =
9
10 * Les acronymes utilisés par la suite sont référencés dans le lexique, à la fin de ce document.
11 * Avoir configuré le serveur DigDash avec un connecteur SSL/TLS (HTTPS) (cette méthode d'authentification requiert des échanges sécurisés).
12 * 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.
13 ** Le dossier apache-tomcat : transposé à **<Install DD>/apache-tomcat**
14 *** Le sous-dossier lib : librairies et fichier de configuration des logs à placer dans **<InstallDD>/apache-tomcat/lib**
15 *** Le sous-dossier webapps : le point d’entrée DigDash (endpoint) dans un .war à placer dans **<Install DD>/apache-tomcat/webapps**
16 * Les manipulations suivantes sont à réaliser le serveur DigDash **stoppé**.
17 * L’utilisateur à authentifier doit exister à la fois chez l’OP et dans le LDAP DigDash.
18
19 (% class="box warningmessage" %)
20 (((
21 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.
22 )))
23
24 = Configuration du serveur DigDash =
25
26 == Copie des librairies ==
27
28 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 :
29
30 (% class="box" %)
31 (((
32 <Install DD>/apache-tomcat/lib
33 )))
34
35 Fichiers à copier :
36
37 |oidc-valve.jar|slf4j-log4j12-1.7.7.jar
38 |slf4j-api-1.7.12.jar|log4j.properties
39 |log4j-1.2.15.jar|
40
41 == Ajout de la valve d’authentification OpenID Connect ==
42
43 Activez la valve d’authentification OpenID Connect dans le fichier **server.xml** situé dans le dossier :
44
45 {{code language="MS-DOS" cssClass="notranslate"}}
46 <digdash_installation>/apache-tomcat/conf
47 {{/code}}
48
49 Pour cela, chercher l’élément **<Host ...>** dans le fichier, décommenter ou y rajouter l’élément **<Valve ...>** ci-dessous :
50
51 (((
52 {{code cssClass="notranslate" language="xml"}}
53 <Valve className="org.bsworks.catalina.authenticator.oidc.OpenIDConnectSSOValve"
54 allowAddr="localhost, 127.0.0.*,0:0:0:0:0:0:0:1"
55 fallbackAuth="LDAP"
56 sharedPasswd="secret"
57 redirect_url="https://localhost:8443/digdash_oidc_endpoint/oidcendpoint"
58 providers="[
59 {
60 name: OpenID Provider name,
61 issuer: issuer,
62 clientId: clientId,
63 clientSecret: clientSecret
64 }
65 ]"
66 usernameClaim="email"
67 additionalScopes="email" ></Valve>
68 {{/code}}
69
70 La valeur de l'attribut className est invariable.
71 Les valeurs des attributs allowAddr, sharedPasswd, redirect_url, providers, usernameClaim, additionalScopes sont variables selon l'installation.
72 )))
73
74 |(% style="width:216px" %)**Attributs**|(% style="width:1204px" %)**Description**
75 |(% style="color:#c0392b; width:216px" %)className //(obligatoire)//     |(% style="width:1204px" %)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.
76 |(% style="color:#27ae60; width:216px" %)(% style="color:#000000" %)allowAddr //(obligatoire)//   (%%) |(% style="width:1204px" %)Adresse IP du serveur.
77 |(% style="color:#27ae60; width:216px" %)(% style="color:#000000" %)fallbackAuth //(obligatoire)//|(% style="width:1204px" %)La méthode d'authentification de repli
78 |(% style="width:216px" %)sharedPasswd //(obligatoire)//     |(% style="width:1204px" %)Le mot de passe partagé et vérifié à l’authentification (voir point II.5)
79 |(% style="width:216px" %)redirect_url //(obligatoire)//     |(% style="width:1204px" %)(((
80 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}}}
81
82 {{{ou}}}
83 La valeur peut être "{{{/digdash_oidc_endpoint/oidcendpoint}}}" ; dans ce cas là, l'adresse DigDash sera calculée selon l'adresse courante.
84 )))
85 |(% style="width:216px" %)cookieTimeOut //(facultatif)//     |(% style="width:1204px" %)(((
86 Facultatif, il s’agit du temps (en secondes) au bout duquel le cookie SSO expirera. Vaut 1800 secondes (30 minutes) par défaut .
87 Sinon, le cookie expirera après le nombre de secondes mentionné.
88
89 La mention d'une valeur négative signifie que le cookie expirera à la fermeture du navigateur.
90 La mention d'une valeur égale à 0 signifie que le cookie sera directement supprimé (non recommandé).
91
92 Exemple : cookieTimeOut="3600" (1 heure)
93 )))
94 |(% style="width:216px" %)print_debug //(facultatif)//     |(% style="width:1204px" %)Facultatif, vaut false par défaut, sinon, ajouter print_debug="true" pour des traces plus verbeuses.
95 |(% style="width:216px" %)providers //(obligatoire)//     |(% style="width:1204px" %)(((
96 Valeur de forme tableau d’objets en JSON. Chaque élément correspond à un OpenID Provider utilisé par l’application.
97
98 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 :
99
100 - **issuer **//(obligatoire) //: Il s’agit d’une URL unique pour identifier l’OP.    
101
102 - **name** //(facultatif) //: Un nom associé à l’OP ; l’issuer sinon par défaut.
103
104 (((
105 - **clientId **//(obligatoire) : //Le client ID associé à l’application chez l’OP.
106
107 - **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.
108
109 - **usernameClaim **//(facultatif) : //L’attribut user Identifier réclamé par le RP et renvoyé par l’OP pour identifier l’utilisateur qui s’authentifie.
110
111 - **additionalScopes **//(facultatif) //: Les scopes additionnels au scope ‘openid’ séparés par des espaces.
112 )))
113 )))
114 |(% style="width:216px" %)usernameClaim //(facultatif)//     |(% style="width:1204px" %)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.
115 |(% style="width:216px" %)additionalScopes (//facultatif)//     |(% style="width:1204px" %)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.
116 |(% style="width:216px" %)httpConnectTimeout //(facultatif)//     |(% style="width:1204px" %)Timeout en millisecondes pour l’établissement de la connexion vers l’OP. 5000 ms (5 secondes) par défaut.
117 |(% style="width:216px" %)ldapForPaths //(facultatif)//     |(% style="width:1204px" %)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/.*"
118
119 == Ajout du .war correspondant au point d’entrée du Relying Party ==
120
121 Ajoutez l’archive **digdash_oidc_endpoint.war** du dossier **<install DD>/add-ons/valve_openidconnect/apache-tomcat/webapps** dans le dossier :
122
123 (% class="box" %)
124 (((
125 <digdash_installation>/apache-tomcat/webapps
126 )))
127
128 (% class="box infomessage" %)
129 (((
130 Il s’agit du point d’entrée (endpoint) du RP accédé par l’OP.
131 )))
132
133 == Ajout des contraintes de sécurité ==
134
135 Décommentez ou ajoutez les contraintes de sécurité au fichier **web.xml** situé dans le dossier :
136
137 (% class="box" %)
138 (((
139 <Install DD>/apache-tomcat/conf
140 )))
141
142 {{code language="xml" cssClass="notranslate"}}
143 <web-app ...>
144 ...
145 <security-role>
146 <role-name>CUSTOM</role-name>
147 </security-role>
148
149 <security-constraint>
150 <display-name>CUSTOM Security Constraint</display-name>
151 <web-resource-collection>
152 <web-resource-name>Protected Area</web-resource-name>
153 <url-pattern>/*</url-pattern>
154 </web-resource-collection>
155
156 <auth-constraint>
157 <role-name>CUSTOM</role-name>
158 </auth-constraint>
159 </security-constraint>
160
161 <security-constraint>
162 <web-resource-collection>
163 <web-resource-name>Non-Protected Area</web-resource-name>
164 <url-pattern>/vjdbc</url-pattern>
165 </web-resource-collection>
166 </security-constraint>
167 ...
168 </web-app>
169 {{/code}}
170
171 (((
172
173 )))
174
175 = Configuration des applications =
176
177 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.
178
179
180 == Configuration du Serveur (ddenterprise.war) ==
181
182 Dans le fichier **digdash.properties** :
183
184 Dans l'encadré //ddenterpriseapi.war//, rechercher et décommenter les lignes suivantes avec les valeurs indiquées :
185
186 {{code language="properties" cssClass="notranslate"}}
187 ddenterpriseapi.authMethod=External
188 {{/code}}
189
190
191 == Configuration du Tableau de bord (digdash_dashboard.war) ==
192
193 Dans le fichier **digdash.properties** :
194
195 Dans l'encadré //digdash_dashbord.war//, rechercher et décommenter les lignes suivantes avec les valeurs indiquées :
196
197 {{code language="properties" cssClass="notranslate"}}
198 digdash_dashboard.SERVERURL=http://localhost:8080
199 digdash_dashboard.DOMAIN=ddenterpriseapi
200 digdash_dashboard.FORCEDOMAIN=true
201 digdash_dashboard.FORCESERVERURL=true
202 digdash_dashboard.sharedPasswd=<la valeur de l'attribut sharedPasswd dans l'élément Valve>
203 {{/code}}
204
205 (% class="box infomessage" %)
206 (((
207 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.
208 )))
209
210
211 == Configuration du Web Studio (studio.war) ==
212
213 Dans le fichier **digdash.properties** :
214
215 Dans l'encadré //studio.war//, rechercher et décommenter les lignes suivantes avec les valeurs indiquées :
216
217 {{code language="properties" cssClass="notranslate"}}
218 studio.SERVERURL=http://localhost:8080
219 studio.DOMAIN=ddenterpriseapi
220 studio.FORCEDOMAIN=true
221 studio.FORCESERVERURL=true
222 studio.PUBLICSERVERURL=<votre adresse URL publique en HTTPS>
223 studio.sharedPasswd=<la valeur de l'attribut sharedPasswd dans l'élément Valve>
224 {{/code}}
225
226 (% class="box infomessage" %)
227 (((
228 La valeur d’exemple pour le paramètre //studio.SERVERURL// 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.
229 )))
230
231
232
233 == Configuration du Desktop Studio (adminconsole.war) ==
234
235 Dans le fichier **digdash.properties** :
236
237 Dans l'encadré //adminconsole.war//, rechercher et décommenter les lignes suivantes avec les valeurs indiquées :
238
239 {{code language="properties" cssClass="notranslate"}}
240 adminconsole.server_domain_list=ddenterpriseapi
241 adminconsole.ddserver=<votre adresse URL publique en HTTPS>
242 adminconsole.serverDomain=ddenterpriseapi
243 adminconsole.domain=ddenterpriseapi
244 adminconsole.authMode=External
245 adminconsole.forceServerDomain=true
246 {{/code}}
247
248
249 = Configuration de l’OpenID Provider =
250
251 L’OP devra enregistrer DigDash en tant que RP dans sa liste de RP pour que DigDash puisse tirer profit de l’Authentification unique.
252
253 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
254
255 (% class="box infomessage" %)
256 (((
257 https:~/~/<adresse du serveur DigDash>:<port>/digdash_oidc_endpoint/oidcendpoint
258 )))
259
260
261 = Niveau de Logs =
262
263 Vous pouvez personnaliser le niveau de log pour la valve d’authentification.
264
265 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.
266
267 log4j.logger.org.bsworks=**ERROR**, stdout
268 devient
269 log4j.logger.org.bsworks=**DEBUG**, stdout
270
271 = Cohabitation OpenID Connect et LDAP DigDash (facultatif) =
272
273 (% class="box infomessage" %)
274 (((
275 Cette fonctionnalité n'est disponible qu'à partir de la version patchée 2021R1_p20220311.
276 )))
277
278 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.
279
280 == Configuration préalable ==
281
282 Dans le fichier **digdash.properties** :
283
284 Dans l'encadré //studio.war//, rechercher et décommenter les lignes suivantes avec les valeurs indiquées :
285
286 {{code language="properties" cssClass="notranslate"}}
287 studio.allowLoginForm=true
288 {{/code}}
289
290 Dans l'encadré //digdash_dashbord.war//, rechercher et décommenter les lignes suivantes avec les valeurs indiquées :
291
292 {{code language="properties" cssClass="notranslate"}}
293 digdash_dashboard.allowLoginForm=true
294 {{/code}}
295
296
297 == Activation du mode LDAP DigDash ==
298
299 Pour activer le mode d'authentification en mode LDAP DigDash, il suffit de rajouter dans l'URL le paramètre **loginForm **avec la valeur (% style="color:#27ae60" %)**true**(%%).
300
301 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 :
302
303 (% class="box" %)
304 (((
305 https:~/~/<host>:<port>/digdash_dashboard/index.html?**loginForm**=(% style="color:#27ae60" %)**true**
306 )))
307
308 (% class="box warningmessage" %)
309 (((
310 (% style="color:#e67e22" %)**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.
311 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.
312 )))
313
314 == Ré-activation du mode OpenID Connect ==
315
316 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 (% style="color:#c0392b" %)**false**(%%).
317 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 :
318
319 (% class="box" %)
320 (((
321 https:~/~/<host>:<port>/digdash_dashboard/index.html?**loginForm**=(% style="color:#c0392b" %)**false**
322 )))
323
324 La note d'avertissement précédente est également à prendre en compte dans ce cas.
325
326
327 {{warning}}
328 Pour passer d'un mode d'authentification à l'autre, il est fortement conseillé de suivre l'une des règles suivantes :
329
330 * se déconnecter de l'utilisateur courant dans le cadre d'une utilisation d'une même session navigateur
331 * utiliser une session navigateur différente (soit en navigation privée sur un même navigateur ou basculer sur un navigateur différent)
332 {{/warning}}
333
334 = Lexique =
335
336 Nous appellerons dans ce document :
337
338 * **Endpoint **: Point d’entrée
339 * **OP **: OpenID Provider ou le Fournisseur d’identités
340 * **RP **: Relying Party ou le Fournisseur de services (DigDash)
341 * **SSO **: Single Sign On ou Authentification unique ; OpenIDConnect est une méthode SSO
342
343 = Références =
344
345 https://www.oasis-open.org
346
347 //DigDash utilise la librairie OpenSource tomcat8-oidcauth de Boyle Software, Inc. pour supporter la méthode d’authentification OpenID Connect.//
348
349 https://www.boylesoftware.com/
350
351 https://github.com/boylesoftware/tomcat8-oidcauth