Code source wiki de Authentification OpenID Connect

Modifié par Aurelie Bertrand le 2025/02/17 17:17

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

Code source wiki de Authentification OpenID Connect

Sommaire