Wiki source code of Authentification OpenID Connect

Last modified by Aurelie Bertrand on 2026/01/12 16:46

version	line-number	content
1.1	1	{{ddtoc/}}
	2
3.1	3	----
	4
2.1	5	(% class="wikigeneratedid" %)
74.1	6	This document describes how to set up an OpenID Connect authentication valve for DigDash.
2.1	7
74.1	8	= Prerequisites =
1.1	9
74.1	10	* The acronyms used below are listed in the glossary at the end of this document.
	11	* Have configured the DigDash server with an SSL/TLS (HTTPS) connector (this authentication method requires secure exchanges).
	12	* Have the <Install DD>/add-ons/valve_openidconnect folder containing all the files needed to set up the OpenID Connect authentication valve in the DigDash Tomcat server. The placement of these files is described in this document.
	13	The apache-tomcat folder: transposed to /etc/tomcat9/ under Linux and C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf **under Windows
	14	*** The lib sub-folder: libraries and logs configuration file to be placed in :
	15	** under Linux: /usr/share/tomcat9/lib/**
	16	** under Windows : C:\Program Files\Apache Software Foundation\Tomcat 9.0\lib**
	17	*** The webapps sub-folder : the DigDash entry point (endpoint) in a .war to be placed in:
	18	** under Linux: /home/digdash/webapps/default**
	19	** under Windows: E:/digdash/webapps/default**
	20	* The following operations must be carried out with the DigDash server stopped.
	21	* The user to be authenticated must exist both at the PO and in the DigDash LDAP.
1.1	22
19.2	23	(% class="box warningmessage" %)
	24	(((
74.1	25	It is advisable to have at least one user with the right to add DigDash users to the DigDash LDAP before installing the OpenID Connect valve, in order to avoid SSO authentication failures on the first connections due to the absence of such a user in the LDAP.
19.2	26	)))
	27
74.1	28	= Configuring the DigDash server =
1.1	29
74.1	30	== Copy the libraries ==
1.1	31
74.1	32	Copy the libraries and the log configuration file from the <install DD>/add-ons/valve_openidconnect/apache-tomcat/lib folder to the :
1.1	33
17.3	34	(% class="box" %)
	35	(((
74.1	36	* under Linux: /usr/share/tomcat9/lib/
	37	* under Windows : C:\Program Files\Apache Software Foundation\Tomcat 9.0\lib
17.3	38	)))
1.1	39
74.1	40	Files to copy :
17.3	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
74.1	45	\|log4j-core-2.19.0.jar\|
1.1	46
74.1	47	== Adding the OpenID Connect authentication valve ==
1.1	48
74.1	49	Activate the OpenID Connect authentication valve in the server.xml file located in the :
1.1	50
69.1	51	(% class="box" %)
	52	(((
74.1	53	* on Linux: /etc/tomcat9/
	54	* under Windows : C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf
69.1	55	)))
1.1	56
74.1	57	To do this, look for the <Host ...> element in the file, uncomment or add the <Valve ...> element below:
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
74.1	81	The value of the className attribute is invariant.
	82	The values of the allowAddr, sharedPasswd, redirect_url, providers, usernameClaim, additionalScopes attributes are variable depending on the installation.
60.1	83
	84	(% class="box infomessage" %)
	85	(((
74.1	86	💡 The cookieTimeOut attribute is optional and can take on different values as described below.
	87	However, it is recommended that //cookieTimeOut="-1"// be used //.//
1.1	88	)))
60.1	89	)))
1.1	90
74.1	91	\|(% style="width:216px" %)Attributes\|(% style="width:1204px" %)Description
	92	\|(% style="color:#c0392b; width:216px" %)className //(required// )\|(% style="width:1204px" %)Name of the Java class implementing the org.apache.catalina.Valve interface, to be used as Valve here. This attribute is mandatory, as it is used to select the Valve to be used. There are several implementations provided by Tomcat.
	93	\|(% style="color:#27ae60; width:216px" %)(% style="color:#000000" %)allowAddr //(required// )\|(% style="width:1204px" %)IP address of the server.
	94	\|(% style="color:#27ae60; width:216px" %)(% style="color:#000000" %)fallbackAuth //(required)//\|(% style="width:1204px" %)The fallback authentication method.
	95	\|(% style="width:216px" %)sharedPasswd //(required// )\|(% style="width:1204px" %)The password shared and verified during authentication (see point II.5).
	96	\|(% style="width:216px" %)redirect_url //(required// )\|(% style="width:1204px" %)(((
	97	This is the application path to which users will be redirected after authenticating with the OP. For DigDash, the URL will be {{{https://<DigDash address>:<port>/digdash_oidc_endpoint/oidcendpoint}}}
54.1	98
74.1	99	{{{or}}}
	100	The value can be{{{"/digdash_oidc_endpoint/oidcendpoint}}}"; in this case, the DigDash address will be calculated according to the current address.
54.1	101	)))
74.1	102	\|(% style="width:216px" %)cookieTimeOut //(optional// )\|(% style="width:1204px" %)(((
	103	Optional, this is the time (in seconds) after which the SSO cookie will expire. Defaults to 1800 seconds (30 minutes).
	104	Otherwise, the cookie will expire after the specified number of seconds.
1.1	105
74.1	106	A negative value means that the cookie will expire when the browser is closed.
	107	A value of 0 means that the cookie will be deleted directly (not recommended).
46.1	108
74.1	109	Example: cookieTimeOut="3600" (1 hour)
1.1	110	)))
74.1	111	\|(% style="width:216px" %)print_debug //(optional// )\|(% style="width:1204px" %)Optional, set to false by default, otherwise add print_debug="true" for more verbose traces.
	112	\|(% style="width:216px" %)providers //(required// )\|(% style="width:1204px" %)(((
	113	JSON object array value. Each element corresponds to an OpenID Provider used by the application.
1.1	114
74.1	115	The syntax differs from the standard JSON format in that double quotes are not used for the names of properties and their values (to make the format more XML-like). A value can be surrounded by single quotes if it contains separators such as commas, braces or spaces. Each object representing a PO has the following properties:
1.1	116
74.1	117	- issuer //(mandatory) //: This is a unique URL to identify the PO.
1.1	118
74.1	119	- name //(optional) //: A name associated with the PO; otherwise the issuer by default.
1.1	120
	121	(((
74.1	122	- clientId //(required): //The client ID associated with the application at the PO.
1.1	123
74.1	124	- clientSecret //(optional) //: The Secret client. Note that most POs require a Secret client, particularly for calls to the PO's entry points. However, some OPs support public clients, hence the absence of a Secret client.
1.1	125
74.1	126	- usernameClaim //(optional): //The user Identifier attribute requested by the RP and returned by the PO to identify the authenticating user.
1.1	127
74.1	128	- additionalScopes //(optional) //: Additional scopes to the 'openid' scope separated by spaces.
1.1	129	)))
	130	)))
74.1	131	\|(% style="width:216px" %)usernameClaim //(optional// )\|(% style="width:1204px" %)The default user identifier used by all OPs that do not specify one in the OP's own properties.
	132	\|(% style="width:216px" %)additionalScopes//(optional// )\|(% style="width:1204px" %)The default additional scopes used by all OPs that do not specify one in the OP's own properties.
	133	\|(% style="width:216px" %)httpConnectTimeout //(optional// )\|(% style="width:1204px" %)Timeout in milliseconds for establishing the connection to the OP. 5000 ms (5 seconds) by default.
	134	\|(% style="width:216px" %)ldapForPaths //(optional// )\|(% style="width:1204px" %)These are the regular expressions of the URLs whose resources are authorised to pass the valve, thereby switching to LDAP authentication mode. Example: "https:~/~/localhost:8443/digdash_dashboard/.*"
	135	\|excludedPaths// (optional)//\|These are the regular expressions of the paths whose resources are authorised to pass the valve, thus switching to LDAP authentication mode. Example: "/.*"
1.1	136
74.1	137	== Add the .war corresponding to the Relying Party entry point ==
1.1	138
74.1	139	Add the digdash_oidc_endpoint.war archive from the <install DD>/add-ons/valve_openidconnect/apache-tomcat/webapps folder to the :
1.1	140
17.3	141	(% class="box" %)
	142	(((
74.1	143	* under Linux: /home/digdash/webapps/default
	144	* under Windows: E:/digdash/webapps/default
17.3	145	)))
1.1	146
19.3	147	(% class="box infomessage" %)
	148	(((
74.1	149	This is the endpoint of the RP accessed by the OP.
19.3	150	)))
1.1	151
74.1	152	== Adding security constraints ==
1.1	153
74.1	154	Uncomment or add the security constraints to the web.xml file located in the :
1.1	155
17.3	156	(% class="box" %)
	157	(((
74.1	158	* under Linux: /etc/tomcat9/
	159	* under 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	(((
74.1	192
	193
1.1	194	)))
	195
74.1	196	= Application configuration =
1.1	197
74.1	198	To do this, modify the digdash.properties file in <install DD> or /etc/digdash (under Linux) or in the folder you have configured.
22.1	199
	200
74.1	201	== Server configuration (ddenterprise.war) ==
22.1	202
74.1	203	In the digdash.properties file:
22.1	204
74.1	205	In the //ddenterpriseapi.war// box, find and uncomment the following lines with the values shown:
22.1	206
45.1	207	{{code language="properties" cssClass="notranslate"}}
32.1	208	ddenterpriseapi.authMethod=External
	209	{{/code}}
22.1	210
	211
74.1	212	== Dashboard configuration (digdash_dashboard.war) ==
22.1	213
74.1	214	In the digdash.properties file :
22.1	215
74.1	216	In the //digdash_dashbord.war// box, find and uncomment the following lines with the values shown:
22.1	217
45.1	218	{{code language="properties" cssClass="notranslate"}}
32.1	219	digdash_dashboard.SERVERURL=http://localhost:8080
	220	digdash_dashboard.DOMAIN=ddenterpriseapi
	221	digdash_dashboard.FORCEDOMAIN=true
	222	digdash_dashboard.FORCESERVERURL=true
	223	digdash_dashboard.sharedPasswd=<la valeur de l'attribut sharedPasswd dans l'élément Valve>
	224	{{/code}}
22.1	225
	226	(% class="box infomessage" %)
	227	(((
74.1	228	The example value for the //digdash_dashboard.SERVERURL// parameter will almost always refer to localhost, when the dashboard and the server are placed in the same Tomcat server, which represents almost 99.9% of usage. Naturally, you will need to refer to the address of the external server if these two elements are located on different servers.
22.1	229	)))
	230
	231
74.1	232	== Studio configuration (studio.war) ==
22.1	233
74.1	234	In the digdash.properties file :
22.1	235
74.1	236	In the //studio.war// box, find and uncomment the following lines with the values shown:
22.1	237
66.1	238	{{code cssClass="notranslate" language="properties"}}
32.1	239	studio.SERVERURL=http://localhost:8080
	240	studio.DOMAIN=ddenterpriseapi
	241	studio.FORCEDOMAIN=true
	242	studio.FORCESERVERURL=true
	243	studio.PUBLICSERVERURL=<votre adresse URL publique en HTTPS>
	244	studio.sharedPasswd=<la valeur de l'attribut sharedPasswd dans l'élément Valve>
	245	{{/code}}
22.1	246
	247	(% class="box infomessage" %)
	248	(((
74.1	249	The parameter //studio.PUBLICSERVERURL// is optional when installing an SSO.
64.1	250
74.1	251	The example value for this parameter will almost always refer to localhost, when the Studio and the server are placed in the same Tomcat server, which represents almost 99.9% of usage. Naturally, you will need to refer to the address of the external server if these two elements are located on different servers.
22.1	252	)))
	253
74.1	254	= Configuring the OpenID Provider =
1.1	255
74.1	256	The PO must register DigDash as an RP in its list of RPs so that DigDash can take advantage of Single Sign-On.
1.1	257
74.1	258	The PO will also need to fill in the callback URL to identify the entry point to the DigDash application. The URL will be in the form
1.1	259
37.1	260	(% class="box infomessage" %)
	261	(((
74.1	262	https:~/~/<address of DigDash server>:<port>/digdash_oidc_endpoint/oidcendpoint
37.1	263	)))
1.1	264
	265
74.1	266	= Log Level =
1.1	267
74.1	268	You can customise the log level for the authentication valve.
1.1	269
74.1	270	By default, only errors are logged. However, if you want to have more details about the actions and exchanges between the various entities, you can set the value to 'DEBUG' instead of 'ERROR' in the log4j.properties file that has been imported into the Tomcat lib folder.
1.1	271
74.1	272	log4j.logger.org.bsworks=ERROR, stdout
	273	becomes
	274	log4j.logger.org.bsworks=DEBUG, stdout
1.1	275
74.1	276	= OpenID Connect and LDAP DigDash coexistence (optional) =
37.1	277
74.1	278	It is possible to combine direct authentication via the DigDash LDAP directory with the OpenID Connect method on your DigDash server.
48.1	279
74.1	280	== Prior configuration ==
48.1	281
74.1	282	In the digdash.properties file :
48.1	283
74.1	284	In the //studio.war// box, find and uncomment the following lines with the values shown:
48.1	285
	286	{{code language="properties" cssClass="notranslate"}}
	287	studio.allowLoginForm=true
	288	{{/code}}
	289
74.1	290	In the //digdash_dashbord.war// box, find and uncomment the following lines with the values shown:
48.1	291
	292	{{code language="properties" cssClass="notranslate"}}
	293	digdash_dashboard.allowLoginForm=true
	294	{{/code}}
	295
	296
74.1	297	== Enabling DigDash LDAP mode ==
48.1	298
74.1	299	To activate the DigDash LDAP authentication mode, simply add the loginForm parameter to the URL with the value (% style="color:#27ae60" %)true(%%).
48.1	300
74.1	301	So, if you need to authenticate to the dashboard directly using your DigDash LDAP credentials when OpenIDConnect is already installed, the URL to use will be in the form :
48.1	302
	303	(% class="box" %)
	304	(((
74.1	305	https:~/~/<host>:<port>/digdash_dashboard/index.html?(% style="color:#27ae60" %)loginForm=true(%%)
48.1	306	)))
	307
	308	(% class="box warningmessage" %)
	309	(((
74.1	310	(% style="color:#e67e22" %)Please note (%%): in general, the loginForm parameter and its value should be specified on each domain independently of the others (ddenterpriseapi for the server, digdash_dashboard for the dashboard, studio for the web studio) to authenticate via LDAP.
	311	So activating the loginForm parameter on the dashboard (digdash_dashboard domain) will not automatically activate it on the web studio (studio domain), for example.
48.1	312	)))
	313
74.1	314	== Re-enabling OpenID Connect mode ==
48.1	315
74.1	316	To deactivate the DigDash LDAP mode and return to a state where OpenID Connect SSO authentication is used, simply set the loginForm parameter to (% style="color:#c0392b" %)false(%%).
	317	If you need to authenticate to the dashboard via OpenID Connect when direct authentication via DigDash LDAP was previously used, the URL to use will be in the form :
48.1	318
	319	(% class="box" %)
	320	(((
74.1	321	https:~/~/<host>:<port>/digdash_dashboard/index.html?(% style="color:#c0392b" %)loginForm=false(%%)
48.1	322	)))
	323
74.1	324	The previous warning note should also be taken into account in this case.\\
48.1	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
74.1	333	= Glossary =
1.1	334
74.1	335	In this document we will refer to :
1.1	336
74.1	337	* Endpoint : Point of entry
	338	* OP : OpenID Provider or Identity Provider
	339	* RP : Relying Party or Service Provider (DigDash)
	340	* SSO : Single Sign On; OpenIDConnect is an SSO method.
14.1	341
74.1	342	= References =
1.1	343
10.1	344	https://www.oasis-open.org
1.1	345
74.1	346	//DigDash uses the tomcat8-oidcauth OpenSource library from Boyle Software, Inc. to support the OpenID Connect authentication method.//
1.1	347
10.1	348	https://www.boylesoftware.com/
1.1	349
10.1	350	https://github.com/boylesoftware/tomcat8-oidcauth

Wiki source code of Authentification OpenID Connect

Sommaire