Modifié par michelhc le 2020/11/20 16:06
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 **<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.
13 ** Le dossier apache-tomcat : transposé à **<digdash_install>/apache-tomcat**
14 *** Le sous-dossier lib : librairies et fichier de configuration des logs à placer dans **<digdash_install>/apache-tomcat/lib**
15 *** Le sous-dossier webapps : le point d’entrée DigDash (endpoint) dans un .war à placer dans **<digdash_install>/apache-tomcat/webapps**
16 * Les manipulations suivantes sont à réaliser le serveur DigDash **stoppé**.
17
18 * L’utilisateur à authentifier doit exister à la fois chez l’OP et dans le LDAP DigDash.
19 ** (% 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.**//
20
21 = Configuration du serveur DigDash =
22
23 == Copie des librairies ==
24
25 Ajouter les librairies ainsi que le fichier de configuration des logs du dossier **apache-tomcat/lib** dans le dossier
26
27 **<digdash_installation>/apache/lib**:
28
29 |oidc-valve.jar|slf4j-log4j12-1.7.7.jar
30 |slf4j-api-1.7.12.jar|log4j.properties
31 |log4j-1.2.15.jar|
32
33 __Librairies du dossier apache-tomcat/lib__
34
35 == Ajout de la valve d’authentification OpenID Connect ==
36
37 Ajouter la valve d’authentification OpenID Connect dans le fichier **server.xml** situé dans le dossier
38
39 {{code language="MS-DOS"}}
40 <digdash_installation>/apache-tomcat/conf
41 {{/code}}
42
43 Pour cela, ajouter l’élément Valve suivant dans l’élément **Host**.
44
45 (((
46 {{code language="xml"}}
47 <Server ... >
48 ...
49 <Host ... >
50 <Valve 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 __Extrait du fichier server.xml__
72
73 La valeur de l'attribut className est invariable.
74 Les valeurs des attributs allowAddr, sharedPasswd, redirect_url, providers, usernameClaim, additionalScopes sont variables selon l'installation.
75
76
77 )))
78
79 |(% style="width:203px" %)Attributs|(% style="width:1641px" %)Description
80 |(% style="color:#c0392b; width:203px" %)className //(obligatoire)//     |(% style="width:1641px" %)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; width:203px" %)allowAddr //(obligatoire)//     |(% style="width:1641px" %)Adresse IP du serveur.
82 |(% style="color:#27ae60; width:203px" %)allowedCtxPath //(facultatif)//     |(% style="width:1641px" %)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 |(% style="width:203px" %)sharedPasswd //(obligatoire)//     |(% style="width:1641px" %)Le mot de passe partagé et vérifié à l’authentification (voir point II.5)
84 |(% style="width:203px" %)redirect_url //(obligatoire)//     |(% style="width:1641px" %)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 |(% style="width:203px" %)cookieTimeOut //(facultatif)//     |(% style="width:1641px" %)(((
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 |(% style="width:203px" %)print_debug //(facultatif)//     |(% style="width:1641px" %)Facultatif, vaut false par défaut, sinon, ajouter print_debug="true" pour des traces plus verbeuses.
92 |(% style="width:203px" %)providers //(obligatoire)//     |(% style="width:1641px" %)(((
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 |(% style="width:203px" %)usernameClaim //(facultatif)//     |(% style="width:1641px" %)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 |(% style="width:203px" %)additionalScopes //(facultatif)//     |(% style="width:1641px" %)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 |(% style="width:203px" %)httpConnectTimeout //(facultatif)//     |(% style="width:1641px" %)Timeout en millisecondes pour l’établissement de la connexion vers l’OP. 5000 ms (5 secondes) par défaut.
114 |(% style="width:203px" %)httpReadTimeout //(facultatif)//     |(% style="width:1641px" %)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"/}}URL du serveur et domaine pour le Dashboard et le Studio Web// ==
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 Faire de même dans le fichier **web.xml **dans **<digdash_installation>/apache-tomcat/webapps/studio/WEB-INF**.
174
175 Pour forcer le domaine, changer la valeur du paramètre **FORCEDOMAIN** à //true//.
176 Mentionner le nom du domaine en changeant le paramètre **DOMAIN**.
177
178 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**.
179
180 {{code language="xml"}}
181 <web-app ...>
182 ...
183 <servlet>
184 <servlet-name>dashServlet</servlet-name>
185 <servlet-class>com.digdash.server.DigdashServiceImpl</servlet-class>
186 ...
187 <init-param>
188 <param-name>DOMAIN</param-name>
189 <param-value>ddenterpriseapi</param-value>
190 </init-param>
191
192 <init-param>
193 <param-name>FORCEDOMAIN</param-name>
194 <param-value>true</param-value>
195 </init-param>
196
197 <init-param>
198 <param-name>SERVERURL</param-name>
199 <param-value>http://localhost:8080</param-value>
200 </init-param>
201
202 <init-param>
203 <param-name>FORCESERVERURL</param-name>
204 <param-value>true</param-value>
205 </init-param>
206 ...
207 </servlet>
208 ...
209 </web-app>
210 {{/code}}
211
212 (((
213 __Extrait du fichier web.xml__
214 \\Les valeurs des paramètres DOMAIN, FORCEDOMAIN, SERVERURL, FORCESERVERURL sont variables selon l'installation.
215
216 )))
217
218 |(% style="width:112px" %)(((
219 [[image:config_auth_oidc_fr_html_829eaa34e529ef0c.png||queryString="width=72&height=72" height="72" width="72"]]
220 )))|(% style="width:1732px" %)(((
221 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.
222 )))
223
224 |[[image:config_auth_oidc_fr_html_829eaa34e529ef0c.png||queryString="width=72&height=72" height="72" width="72"]]
225 |(((
226 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
227
228 (((
229 **<utilisateur>/Application Data/Enterprise Server/dashboard_system.xml **
230
231 Pour en savoir plus, vous pouvez vous référer à la documentation DigDash « guide_avance_systeme_fr.pdf ».
232 )))
233 )))
234
235 == Changement de la valeur du paramètre sharedPasswd ==
236
237 Changer la valeur du paramètre //sharedPasswd// (valeur secret ci-dessous à changer) dans le fichier **web.xml** de Dashboard dans le dossier
238
239 **<digdash_installation>/apache-tomcat/webapps/digdash_dashboard/WEB-INF**
240
241
242
243 ainsi que dans
244
245 **<digdash_installation>/apache-tomcat/webapps/studio/WEB-INF**
246
247 La valeur doit correspondre à celle mentionnée dans l’attribut //sharedPasswd// dans la valve du fichier
248
249 **<digdash_installation>/apache-tomcat/conf/server.xml** (voir partie II.2).
250
251 {{code language="xml"}}
252 <web-app ...>
253 ...
254 <servlet>
255 <servlet-name>dashServlet</servlet-name>
256 <servlet-class>com.digdash.server.DigdashServiceImpl</servlet-class>
257 ...
258 <init-param>
259 <param-name>sharedPasswd</param-name>
260 <param-value>secret</param-value>
261 </init-param>
262 ...
263 </servlet>
264 ...
265  </web-app>
266 {{/code}}
267
268 (((
269 __Extrait du fichier server.xml__
270 \\La valeur du paramètre sharedPasswd est variable selon l'installation.
271 )))
272
273 == Modification de la méthode d'authentification ==
274
275 Modifier la méthode d'authentification (LDAP est la méthode par défaut) dans le fichier **web.xml** situé dans le dossier
276
277 **<digdash_installation>/apache-tomcat/webapps/ddenterpriseapi/WEB-INF**.
278
279 "External" signifie que la sécurité est gérée par la valve configurée ci-dessus.
280
281 {{code language="xml"}}
282 <web-app ...>
283 ...
284 <servlet>
285 ...
286 </servlet>
287 ...
288 <servlet>
289 <description></description>
290 <display-name>DDEnterpriseAuthServlet</display-name>
291 <servlet-name>DDEnterpriseAuthServlet</servlet-name>
292 <servlet-class>com.digdash.server.DDEnterpriseAuthServlet</servlet-class>
293
294 <init-param>
295 <param-name>authMethod</param-name>
296 <param-value>External</param-value>
297 </init-param>
298 ...
299 </servlet>
300 ...
301  </web-app>
302 {{/code}}
303
304 (((
305 __Extrait du fichier web.xml__
306 )))
307
308 = Configuration de l’OpenID Provider =
309
310 L’OP devra enregistrer DigDash en tant que RP dans sa liste de RP pour que DigDash puisse tirer profit de l’Authentification unique.
311
312 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
313
314 https:~/~/<adresse IP>:<port>/digdash_oidc_endpoint/oidcendpoint
315
316 = Niveau de Logs =
317
318 Vous pouvez personnaliser le niveau de log pour la valve d’authentification.
319
320 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.
321
322 log4j.logger.org.bsworks=**ERROR**, stdout
323
324 log4j.logger.org.bsworks=**DEBUG**, stdout
325
326 = Authentification OpenID Connect côté Enterprise Studio =
327
328 Pour vous authentifier avec OpenID Connect côté Enterprise Studio, veuillez vous assurer d’avoir réalisé les actions suivantes :
329
330 == Définitions du serveur et du domaine dans le fichier .jnlp ==
331
332 Vous pouvez, à l’instar du Dashboard, définir le serveur et le domaine sur lequel DigDash va s’appuyer.
333
334 Pour ce faire, modifier la fin du fichier digdash.jnlp dans le dossier d’installation DigDash **<digdash_installation>/apache-tomcat/webapps/adminconsole**
335
336 (((
337 {{code language="XML"}}
338 <jnlp ...>
339 ...
340 <application-desc main-class="commandline.CommandLineMain">
341 <argument>https://localhost:8443</argument> (1)
342 <argument>ddenterpriseapi</argument> (2)
343 <argument><%=lang%></argument> (3)
344 <argument><%=dashboard%></argument> (4)
345 <argument>-AuthMode=External</argument> (5)
346 <argument>-SSLNoPathCheck</argument> (A)
347 ...
348 </application-desc>
349 </jnlp>
350 {{/code}}
351
352 __Extrait du fichier digdash.jnlp__
353 )))
354
355 (% class="box warningmessage" %)
356 (((
357 __**Attention**__** **: les arguments notées (1), (2), (3), (4), (5) ne doivent pas changer d’ordre.
358 )))
359
360 Argument (1) : l’adresse du serveur DigDash ; variable selon votre installation
361
362 Argument (2) : le nom du domaine DigDash ; variable selon votre installation
363
364 Argument (5) : La méthode d’authentification ; External, obligatoirement
365
366 Argument (A) : argument facultatif, parfois nécessaire dans les cas de connexions SSL, HTTPS.
367
368
369 == Connexion au DigDash Enterprise Studio ==
370
371 Télécharger et exécuter le .jnlp en vous rendant sur la page d’accueil DigDash dans la partie Enterprise Studio.
372
373 [[image:2020-09-09_16h54_36.png]]
374
375 Une fenêtre d’authentification doit apparaître avec la mire d’authentification de l’IdP.
376
377 Dans ce document, Google est l’OP que nous avons choisi pour illustrer nos exemples.
378
379 [[image:config_auth_oidc_fr_html_4273fd0e30eb8463.png||queryString="width=632&height=388" height="388" width="632"]]
380 \\
381
382 __Capture : mire avec formulaire d’authentification de l’OP Google__
383
384
385 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.
386
387 [[image:config_auth_oidc_fr_html_6230a5f637fd4c54.png||queryString="width=608&height=372" height="372" width="608"]]
388 \\
389
390 __Capture : fenêtre d’une authentification réussie__
391
392 La fenêtre se fermera automatiquement, puis l’Enterprise Studio débutera son chargement pour se lancer.
393
394 = Lexique =
395
396 Nous appellerons dans ce document :
397
398 * SSO : Single Sign On ou Authentification unique ; OpenIDConnect est une méthode SSO
399 * OP : OpenID Provider ou le Fournisseur d’identités
400 * RP : le Relying Party ou le Fournisseur de services (DigDash)
401 * Endpoint : Point d’entrée
402
403 = Références =
404
405 https:~/~/www.oasis-open.org
406
407
408 //DigDash utilise la librairie OpenSource tomcat8-oidcauth de Boyle Software, Inc. pour supporter la méhode d’authentification OpenID Connect.//
409
410 https:~/~/www.boylesoftware.com/
411
412 https:~/~/github.com/boylesoftware/tomcat8-oidcauth