Modifié par jhurst le 2024/04/02 14:26
Afficher les derniers auteurs
1 **Configuration**
2
3 Mise en place d’une valve d’authentification OpenID Connect pour DigDash
4
5 {{ddtoc/}}
6
7 = Prérequis =
8
9 * Les acronymes utilisés par la suite sont référencés dans le lexique, à la fin de ce document.
10 * Avoir configuré le serveur DigDash avec un connecteur SSL/TLS (HTTPS) (cette méthode d'authentification requiert des échanges sécurisés)
11 * 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.
12 ** Le dossier apache-tomcat : transposé à **<digdash_install>/apache-tomcat**
13 *** Le sous-dossier lib : librairies et fichier de configuration des logs à placer dans **<digdash_install>/apache-tomcat/lib**
14 *** Le sous-dossier webapps : le point d’entrée DigDash (endpoint) dans un .war à placer dans **<digdash_install>/apache-tomcat/webapps**
15 * Les manipulations suivantes sont à réaliser le serveur DigDash **stoppé**.
16
17 * L’utilisateur à authentifier doit exister à la fois chez l’OP et dans le LDAP DigDash.
18 ** (% style="color:#d35400" %)//**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.**//
19
20 = Configuration du serveur DigDash =
21
22 == Copie des librairies ==
23
24 Ajouter les librairies ainsi que le fichier de configuration des logs du dossier **apache-tomcat/lib** dans le dossier
25
26 **<digdash_installation>/apache/lib**:
27
28 |oidc-valve.jar|slf4j-log4j12-1.7.7.jar
29 |slf4j-api-1.7.12.jar|log4j.properties
30 |log4j-1.2.15.jar|
31
32 __Librairies du dossier apache-tomcat/lib__
33
34 == Ajout de la valve d’authentification OpenID Connect ==
35
36 Ajouter la valve d’authentification OpenID Connect dans le fichier **server.xml** situé dans le dossier
37
38 {{code language="MS-DOS"}}
39 <digdash_installation>/apache-tomcat/conf
40 {{/code}}
41
42 Pour cela, ajouter l’élément Valve suivant dans l’élément **Host**.
43
44 (((
45 {{code language="xml"}}
46 <Server ...>
47 ...
48 <Host ...>
49 <Valve
50 className="org.bsworks.catalina.authenticator.oidc.OpenIDConnectSSOValve"
51 allowAddr="localhost,127.0.0.*,0:0:0:0:0:0:0:1"
52 sharedPasswd="secret"
53 redirect_url="https://localhost:8443/digdash_oidc_endpoint/oidcendpoint"
54 providers="[
55 {
56 name: OpenID Provider name,
57 issuer: issuer,
58 clientId: clientId,
59 clientSecret: clientSecret
60 }
61 ]"
62 usernameClaim="email"
63 additionalScopes="email"
64 ></Valve>
65 ...
66 </Host>
67 ...
68 </Server>
69 {{/code}}
70
71
72 (% style="color:#c0392b" %)Valeur invariable
73
74 (% style="color:#27ae60" %)Valeur variable selon l’installation
75
76 Extrait du fichier server.xml
77 )))
78
79 |Attributs|Description
80 |(% style="color:#c0392b" %)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.
81 |(% style="color:#27ae60" %)allowAddr //(obligatoire)//     |Adresse IP du serveur.
82 |(% style="color:#27ae60" %)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"
83 |sharedPasswd //(obligatoire)//     |Le mot de passe partagé et vérifié à l’authentification (voir point II.5)
84 |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
85 |cookieTimeOut //(facultatif)//     |(((
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 Exemple : cookieTimeOut="3600" (1 heure)
90 )))
91 |print_debug //(facultatif)//     |Facultatif, vaut false par défaut, sinon, ajouter print_debug="true" pour des traces plus verbeuses.
92 |providers //(obligatoire)//     |(((
93 Valeur de forme tableau d’objets en JSON. Chaque élément correspond à un OpenID Provider utilisé par l’application.
94
95 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 :
96
97 - **issuer** //(obligatoire) //: Il s’agit d’une URL unique pour identifier l’OP.    
98
99 - **name** //(facultatif) //: Un nom associé à l’OP ; l’issuer sinon par défaut.
100
101 (((
102 - **clientId** //(obligatoire) : //Le client ID associé à l’application chez l’OP.
103
104 - **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.
105
106 - **usernameClaim** //(facultatif) : //L’attribut user Identifier réclamé par le RP et renvoyé par l’OP pour identifier l’utilisateur qui s’authentifie.
107
108 - **additionalScopes** //(facultatif) //: Les scopes additionnels au scope ‘openid’ séparés par des espaces.
109 )))
110 )))
111 |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.
112 |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.
113 |httpConnectTimeout //(facultatif)//     |Timeout en millisecondes pour l’établissement de la connexion vers l’OP. 5000 ms (5 secondes) par défaut.
114 |httpReadTimeout //(facultatif)//     |Timeout en millisecondes pour la lecture des données reçues de l’OP. 5000 ms (5 secondes) par défaut.
115
116 __Tableau décrivant les attributs de l’élément Vavle__
117
118 == Ajout du .war correspondant au point d’entrée du Relying Party ==
119
120 Ajouter l’archive **digdash_oidc_endpoint.war** du dossier **apache-tomcat/webapps** dans le dossier
121
122 **<digdash_installation>/apache-tomcat/webapps**.
123
124 Il s’agit du point d’entrée (endpoint) du RP accédé par l’OP.
125
126 == Ajout des contraintes de sécurité ==
127
128 Ajouter les contraintes de sécurité au fichier **web.xml** situé dans le dossier
129
130 **<digdash_installation>/apache-tomcat/conf**.
131
132 {{code language="xml"}}
133 <web-app ...>
134 ...
135 <security-role>
136 <role-name>CUSTOM</role-name>
137 </security-role>
138
139 <security-constraint>
140 <display-name>CUSTOM Security Constraint</display-name>
141 <web-resource-collection>
142 <web-resource-name>Protected Area</web-resource-name>
143 <url-pattern>/*</url-pattern>
144 </web-resource-collection>
145
146 <auth-constraint>
147 <role-name>CUSTOM</role-name>
148 </auth-constraint>
149 </security-constraint>
150
151 <security-constraint>
152 <web-resource-collection>
153 <web-resource-name>Non-Protected Area</web-resource-name>
154 <url-pattern>/vjdbc</url-pattern>
155 </web-resource-collection>
156 </security-constraint>
157 ...
158 </web-app>
159 {{/code}}
160
161 (((
162 __Extrait du fichier web.xml__
163 )))
164
165 //{{id name="__RefHeading___Toc3170_166059951"/}}II.5 URL du serveur et domaine pour le Dashboard//
166
167 Il peut être nécessaire, et **il est conseillé** de préciser sur quel serveur/domaine le Dashboard va s’appuyer.
168
169 Pour cela, modifier dans le fichier **web.xml** dans
170
171 **<digdash_installation>/apache-tomcat/webapps/digdash_dashboard/WEB-INF.**
172
173 Pour forcer le domaine, changer la valeur du paramètre **FORCEDOMAIN** à //true//.
174 Mentionner le nom du domaine en changeant le paramètre **DOMAIN**.
175
176 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**.
177
178 {{code language="xml"}}
179 <web-app ...>
180 ...
181 <servlet>
182 <servlet-name>dashServlet</servlet-name>
183 <servlet-class>com.digdash.server.DigdashServiceImpl</servlet-class>
184 ...
185 <init-param>
186 <param-name>DOMAIN</param-name>
187 <param-value>ddenterpriseapi</param-value>
188 </init-param>
189
190 <init-param>
191 <param-name>FORCEDOMAIN</param-name>
192 <param-value>true</param-value>
193 </init-param>
194
195 <init-param>
196 <param-name>SERVERURL</param-name>
197 <param-value>http://localhost:8080</param-value>
198 </init-param>
199
200 <init-param>
201 <param-name>FORCESERVERURL</param-name>
202 <param-value>true</param-value>
203 </init-param>
204 ...
205 </servlet>
206 ...
207 </web-app>
208 {{/code}}
209
210 (((
211 __Extrait du fichier web.xml__
212 Valeur variable selon l’installation
213 )))
214
215 |(((
216 * [[image:config_auth_oidc_fr_html_829eaa34e529ef0c.png||queryString="width=72&height=72" height="72" width="72"]]
217 )))|(((
218 * 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.
219 )))
220
221 |[[image:config_auth_oidc_fr_html_829eaa34e529ef0c.png||queryString="width=72&height=72" height="72" width="72"]]
222 |(((
223 * 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(((
224 **<utilisateur>/Application Data/Enterprise Server/dashboard_system.xml **
225
226 Pour en savoir plus, vous pouvez vous référer à la documentation DigDash « guide_avance_systeme_fr.pdf ».
227 )))
228 )))
229
230 == Changement de la valeur du paramètre sharedPasswd ==
231
232 Changer la valeur du paramètre //sharedPasswd// (valeur secret ci-dessous à changer) dans le fichier **web.xml** de Dashboard dans le dossier
233
234 **<digdash_installation>/apache-tomcat/webapps/digdash_dashboard/WEB-INF**.
235
236 La valeur doit correspondre à celle mentionnée dans l’attribut //sharedPasswd// dans la valve du fichier
237
238 **<digdash_installation>/apache-tomcat/conf/server.xml** (voir partie II.2).
239
240 {{code language="xml"}}
241 <web-app ...>
242 ...
243 <servlet>
244 <servlet-name>dashServlet</servlet-name>
245 <servlet-class>com.digdash.server.DigdashServiceImpl</servlet-class>
246 ...
247 <init-param>
248 <param-name>sharedPasswd</param-name>
249 <param-value>secret</param-value>
250 </init-param>
251 ...
252 </servlet>
253 ...
254  </web-app>
255 {{/code}}
256
257 (((
258 Valeur variable selon l’installation
259
260
261 )))
262
263 __Extrait du fichier server.xml__
264
265 == Modification de la méthode d'authentification ==
266
267 Modifier la méthode d'authentification (LDAP est la méthode par défaut) dans le fichier **web.xml** situé dans le dossier
268
269 **<digdash_installation>/apache-tomcat/webapps/ddenterpriseapi/WEB-INF**.
270
271 "External" signifie que la sécurité est gérée par la valve configurée ci-dessus.
272
273 {{code language="xml"}}
274 <web-app ...>
275 ...
276 <servlet>
277 ...
278 </servlet>
279 ...
280 <servlet>
281 <description></description>
282 <display-name>DDEnterpriseAuthServlet</display-name>
283 <servlet-name>DDEnterpriseAuthServlet</servlet-name>
284 <servlet-class>com.digdash.server.DDEnterpriseAuthServlet</servlet-class>
285
286 <init-param>
287 <param-name>authMethod</param-name>
288 <param-value>External</param-value>
289 </init-param>
290 ...
291 </servlet>
292 ...
293  </web-app>
294 {{/code}}
295
296 (((
297 __Extrait du fichier web.xml__
298 )))
299
300 = Configuration de l’OpenID Provider =
301
302 L’OP devra enregistrer DigDash en tant que RP dans sa liste de RP pour que DigDash puisse tirer profit de l’Authentification unique.
303
304 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
305
306 https:~/~/<adresse IP>:<port>/digdash_oidc_endpoint/oidcendpoint
307
308 = Niveau de Logs =
309
310 Vous pouvez personnaliser le niveau de log pour la valve d’authentification.
311
312 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.
313
314 log4j.logger.org.bsworks=**ERROR**, stdout
315
316 log4j.logger.org.bsworks=**DEBUG**, stdout
317
318 = Authentification OpenID Connect côté Enterprise Studio =
319
320 Pour vous authentifier avec OpenID Connect côté Enterprise Studio, veuillez vous assurer d’avoir réalisé les actions suivantes :
321
322 == Définitions du serveur et du domaine dans le fichier .jnlp ==
323
324 Vous pouvez, à l’instar du Dashboard, définir le serveur et le domaine sur lequel DigDash va s’appuyer.
325
326 Pour ce faire, modifier la fin du fichier digdash.jnlp dans le dossier d’installation DigDash **<digdash_installation>/apache-tomcat/webapps/adminconsole**
327
328 (((
329 {{code language="JAVA"}}
330 <jnlp ...>
331
332 ...
333
334 <application-desc main-class="commandline.CommandLineMain">
335
336 <argument>https://localhost:8443</argument> (1)
337
338 <argument>ddenterpriseapi</argument> (2)
339
340 <argument><%=lang%></argument> (3)
341
342 <argument><%=dashboard%></argument> (4)
343
344 <argument>-AuthMode=External</argument> (5)
345
346 <argument>-SSLNoPathCheck</argument> (A)
347
348 ...
349
350 </application-desc>
351
352 </jnlp>
353 {{/code}}
354
355 __Extrait du fichier digdash.jnlp__
356 )))
357
358 (% class="box warningmessage" %)
359 (((
360 __**Attention**__** **: les arguments notées (1), (2), (3), (4), (5) ne doivent pas changer d’ordre.
361 )))
362
363 Argument (1) : l’adresse du serveur DigDash ; variable selon votre installation
364
365 Argument (2) : le nom du domaine DigDash ; variable selon votre installation
366
367 Argument (5) : La méthode d’authentification ; External, obligatoirement
368
369 Argument (A) : argument facultatif, parfois nécessaire dans les cas de connexions SSL, HTTPS.
370
371
372 == Connexion au DigDash Enterprise Studio ==
373
374 Télécharger et exécuter le .jnlp en vous rendant sur la page d’accueil DigDash dans la partie Enterprise Studio.
375
376 [[image:config_auth_oidc_fr_html_27c2ab581e0d9d7e.png||queryString="width=554&height=274" height="274" width="554"]]
377 \\
378
379 Une fenêtre d’authentification doit apparaître avec la mire d’authentification de l’IdP.
380
381 Dans ce document, Google est l’OP que nous avons choisi pour illustrer nos exemples.
382
383 [[image:config_auth_oidc_fr_html_4273fd0e30eb8463.png||queryString="width=632&height=388" height="388" width="632"]]
384 \\
385
386 __Capture : mire avec formulaire d’authentification de l’OP Google__
387
388
389 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.
390
391 [[image:config_auth_oidc_fr_html_6230a5f637fd4c54.png||queryString="width=608&height=372" height="372" width="608"]]
392 \\
393
394 __Capture : fenêtre d’une authentification réussie__
395
396 La fenêtre se fermera automatiquement, puis l’Enterprise Studio débutera son chargement pour se lancer.
397
398 = Lexique =
399
400 * Nous appellerons dans ce document :
401 ** SSO : Single Sign On ou Authentification unique ; OpenIDConnect est une méthode SSO
402 ** OP : OpenID Provider ou le Fournisseur d’identités
403 ** RP : le Relying Party ou le Fournisseur de services (DigDash)
404 ** Endpoint : Point d’entrée
405
406 = Références =
407
408 https:~/~/www.oasis-open.org
409
410
411 //DigDash utilise la librairie OpenSource tomcat8-oidcauth de Boyle Software, Inc. pour supporter la méhode d’authentification OpenID Connect.//
412
413 https:~/~/www.boylesoftware.com/
414
415 https:~/~/github.com/boylesoftware/tomcat8-oidcauth