Language	Title	Date
en	-	-
fr	-	-
es	-	-

Wiki source code of Authentification OpenID Connect

Last modified by Aurelie Bertrand on 2025/02/07 10:19

version	line-number	content
73.1	1	Configuration
1.1	2
73.1	3	Installation of an OpenID Connect authentication valve for DigDash
3.1	4
73.1	5	Contents
2.1	6
73.1	7	{{toc/}}
1.1	8
73.1	9	= Prerequisites =
1.1	10
73.1	11	* The acronyms used later are referenced in the glossary at the end of this document.
	12	* Having configured the DigDash server with an SSL / TLS (HTTPS) connector (this authentication method requires secure exchanges)
	13	* Have the <digdash_installation> / add-ons / valve_openidconnect folder containing all the files necessary for setting up the OpenID Connect authentication valve in the DigDash Tomcat server. The placement of these files is described in this document.
	14	The apache-tomcat folder: transposed to <digdash_install>/apache-tomcat**
	15	* The lib sub-folder: libraries and log configuration file to be placed in <digdash_install>/apache-tomcat/lib**
	16	* The webapps sub-folder: the DigDash entry point (endpoint) in a .war to place in <digdash_install>/apache-tomcat/webapps**
	17	* The following operations are to be performed on the stopped DigDash server .
19.2	18
73.1	19	* The user to be authenticated must exist at both the OP and in the LDAP DigDash.
	20	//It is therefore advisable to have at least one user having the rights to add DigDash users in the LDAP DigDash before installing the OpenID Connect valve, this in order to avoid SSO authentication failures from the first connections for cause of absence of such user in LDAP.**//
1.1	21
73.1	22	= Configuration of the DigDash server =
1.1	23
73.1	24	== Copy of libraries ==
1.1	25
73.1	26	Add the libraries and the log configuration file from the apache-tomcat / lib folder to the folder
1.1	27
73.1	28	<digdash_installation> / apache / lib :
17.3	29
73.1	30	\|oidc-valve.jar\|slf4j-log4j12-1.7.7.jar
	31	\|slf4j-api-1.7.12.jar\|log4j.properties
	32	\|log4j-1.2.15.jar\|
1.1	33
73.1	34	__Libraries in the apache-tomcat/lib folder__
1.1	35
73.1	36	== Addition of the OpenID Connect authentication valve ==
1.1	37
73.1	38	Add the OpenID Connect authentication valve in the server.xml file located in the folder
1.1	39
73.1	40	<digdash_installation>/apache-tomcat/conf
1.1	41
73.1	42	To do this, add the following Valve element in the Host element .
	43
	44	{{code language="XML" cssClass="notranslate"}}
	45	<Server ... >
	46	...
	47	<Host ... >
	48	<Valve className="org.bsworks.catalina.authenticator.oidc.OpenIDConnectSSOValve"
	49	allowAddr="localhost, 127.0.0.*,0:0:0:0:0:0:0:1"
	50	sharedPasswd="secret"
	51	redirect_url="https://localhost:8443/digdash_oidc_endpoint/oidcendpoint"
	52	providers="[
60.1	53	{
73.1	54	name: OpenID Provider name,
	55	issuer: issuer,
	56	clientId: clientId,
	57	clientSecret: clientSecret
60.1	58	}
73.1	59	]"
	60	usernameClaim="email"
	61	additionalScopes="email"
	62	></Valve>
	63	...
	64	</Host>
	65	...
	66	</Server>
1.1	67	{{/code}}
	68
73.1	69	__Extract from the server.xml file__
60.1	70
73.1	71	Value for parameter className is invariable.
	72	Values for parameters allowAddr, sharedPasswd, redirect_url, providers, usernameClaim, additionalScopes are variable according to the installation.
1.1	73
54.1	74
73.1	75	\|(% style="width:201px" %)Attributes\|(% style="width:1219px" %)Description
	76	\|(% style="color:#e74c3c; width:201px" %)className //(required)// \|(% style="width:1219px" %)Name of the Java class, implementing the org.apache.catalina.Valve interface, to use as Valve here. This attribute is mandatory because it allows you to select the Valve to use. There are indeed several implementations provided by Tomcat.
	77	\|(% style="color:#27ae60; width:201px" %)allowAddr //(required)// \|(% style="width:1219px" %)Server IP address.
	78	\|(% style="color:#27ae60; width:201px" %)allowedCtxPath //(optional)// \|(% style="width:1219px" %)Optional, is "/ adminconsole" by default; it is the path of the context whose resources are authorized to pass the valve, useful when the adminconsole is named differently. Example: allowedCtxPath = "/ customadminconsole"
	79	\|(% style="color:#27ae60; width:201px" %)sharedPasswd //(required)// \|(% style="width:1219px" %)The shared password and verified at authentication (see point II.5)
	80	\|(% style="color:#27ae60; width:201px" %)redirect_url //(required)// \|(% style="width:1219px" %)This is the path of the application to which users will be redirected after authenticating with the OP. For DigDash, the URL will always be [[https: ~~/~~/>>path:https:]] <IPaddress>: <port> / digdash_oidc_endpoint / oidcendpoint
	81	\|(% style="color:#27ae60; width:201px" %)cookieTimeOut //(optional)// \|(% style="width:1219px" %)(((
	82	Optional, this is the time (in seconds) after which the SSO cookie will expire. Worth 1800 seconds (30 minutes) by default.
	83	Otherwise, the cookie will expire after the number of seconds mentioned.
1.1	84
73.1	85	Example: cookieTimeOut = "3600" (1 hour)
1.1	86	)))
73.1	87	\|(% style="color:#27ae60; width:201px" %)print_debug //(optional)// \|(% style="width:1219px" %)Optional, is false by default, otherwise add print_debug = "true" for more verbose traces.
	88	\|(% style="width:201px" %)providers //(required)// \|(% style="width:1219px" %)(((
	89	Array form value of objects in JSON. Each element corresponds to an OpenID Provider used by the application.
1.1	90
73.1	91	The syntax differs from the standard JSON format in that double quotes are not used for the names of properties and their values (so as to make the format more XMLian). A value can be surrounded by single quotes if it contains separators such as a comma, braces, or spaces. Each object representing a PO has the following properties:
1.1	92
73.1	93	- issuer //(mandatory) // : This is the only one with a unique URL to identify the OP.
1.1	94
73.1	95	- name //(optional) // : A name associated with the PO; if not by default.
1.1	96
	97	(((
73.1	98	- clientId //(mandatory): // The client ID associated with the application at the PO.
1.1	99
73.1	100	- clientSecret //(optional) // : The Secret client. Note that most POs require a Secret client, especially for calls to PO entry points. However, some OPs support public clients, hence the absence of a Secret client.
1.1	101
73.1	102	- usernameClaim //(optional): // The user Identifier attribute requested by the RP and returned by the OP to identify the user who authenticates.
1.1	103
73.1	104	- additionalScopes //(optional) // : Additional scopes with an 'openid' scope separated by spaces.
1.1	105	)))
	106	)))
73.1	107	\|(% style="width:201px" %)usernameClaim //(optional)// \|(% style="width:1219px" %)The default User Identifier used by all OPs which do not specify one in the proper properties of the OP.
	108	\|(% style="width:201px" %)additionalScopes //(optional)// \|(% style="width:1219px" %)The default additional scopes used by all OPs which do not specify one in the proper properties of the OP.
	109	\|(% style="width:201px" %)httpConnectTimeout //(optional)// \|(% style="width:1219px" %)Timeout in milliseconds for establishing the connection to the OP. 5000 ms (5 seconds) by default.
	110	\|(% style="width:201px" %)httpReadTimeout //(optional)// \|(% style="width:1219px" %)Timeout in milliseconds for reading data received from the OP. 5000 ms (5 seconds) by default.
1.1	111
73.1	112	__Table describing the attributes of the Vavle element__
1.1	113
73.1	114	== Addition of the .war corresponding to the entry point of the Relying Party ==
1.1	115
73.1	116	Add the digdash_oidc_endpoint.war archive from the apache-tomcat/webapps folder to the folder
1.1	117
73.1	118	<digdash_installation>/apache-tomcat/webapps.
1.1	119
73.1	120	It is the entry point (endpoint) of the RP accessed by the PO.
1.1	121
73.1	122	== Addition of security constraints ==
1.1	123
73.1	124	Add the security constraints to the web.xml file located in the folder
1.1	125
73.1	126	<digdash_installation>/apache-tomcat/conf .
1.1	127
73.1	128	{{code cssClass="notranslate"}}
	129	<web-app ... >
	130	...
	131	<security-role>
	132	<role-name>CUSTOM</role-name>
	133	</security-role>
1.1	134
73.1	135	<security-constraint>
	136	<display-name>CUSTOM Security Constraint</display-name>
	137	<web-resource-collection>
	138	<web-resource-name>Protected Area</web-resource-name>
	139	<url-pattern>/*</url-pattern>
	140	</web-resource-collection>
	141	<auth-constraint>
	142	<role-name>CUSTOM</role-name>
	143	</auth-constraint>
	144	</security-constraint>
1.1	145
73.1	146	<security-constraint>
	147	<web-resource-collection>
	148	<web-resource-name>Non-Protected Area</web-resource-name>
	149	<url-pattern>/vjdbc</url-pattern>
	150	</web-resource-collection>
	151	</security-constraint>
	152	...
1.1	153	</web-app>
	154	{{/code}}
	155
73.1	156	__Extract from web.xml file__
1.1	157
73.1	158	== Server URL and domain for the Dashboard and Web Studio ==
1.1	159
73.1	160	It may be necessary, and it is advisable to specify on which server / domain the Dashboard will rely.
22.1	161
73.1	162	To do this, modify in the web.xml file in <digdash_installation>/apache-tomcat/webapps/digdash_dashboard /WEB-INF.
22.1	163
73.1	164	Do the same for the web.xml file in <digdash_installation>/apache-tomcat/webapps/studio/WEB-INF
22.1	165
73.1	166	To force the domain, change the value of the FORCEDOMAIN parameter to //true// .
	167	Mention the domain name by changing the DOMAIN parameter .
22.1	168
73.1	169	To force the server address, change the value of the FORCEURLSERVER parameter to //true// . Mention the server address by changing the SERVERURL parameter .
22.1	170
73.1	171	{{code cssClass="notranslate"}}
	172	<web-app ... >
	173	...
	174	<servlet>
	175	<servlet-name>dashServlet</servlet-name>
	176	<servlet-class>com.digdash.server.DigdashServiceImpl</servlet-class>
	177	...
	178	<init-param>
	179	<param-name>DOMAIN</param-name>
	180	<param-value>ddenterpriseapi</param-value>
	181	</init-param>
	182	<init-param>
	183	<param-name>FORCEDOMAIN</param-name>
	184	< param-value>true</param-value>
	185	</init-param>
	186	<init-param>
	187	<param-name>SERVERURL</ param-name>
	188	<param-value>http://localhost:8080</param-value>
	189	</init-param>
	190	<init-param>
	191	<param-name>FORCESERVERURL</param-name>
	192	<param-value>true</param-value>
	193	</init-param>
	194	...
	195	</servlet>
	196	...
	197	</web-app>
32.1	198	{{/code}}
22.1	199
73.1	200	__Extract from web.xml file__
22.1	201
73.1	202	Values for parameters DOMAIN, FORCEDOAMIN, SERVERUEL, FORCESERVERURL are variable according to the installation.
22.1	203
	204
73.1	205	\|(((
	206	* [[image:http://rack-lure:8585/bin/download/Digdash_2019R2/others_documents/config_auth_oidc/WebHome/config_auth_oidc_fr_html_829eaa34e529ef0c.png?width=72&height=72&rev=1.1\|\|alt="config_auth_oidc_fr_html_829eaa34e529ef0c.png"]]
	207	)))\|(((
	208	The example value for the 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% of the uses. It will naturally be necessary to refer to the address of the external server if these two elements are placed on different servers.
	209	)))
22.1	210
73.1	211	\|[[image:http://rack-lure:8585/bin/download/Digdash_2019R2/others_documents/config_auth_oidc/WebHome/config_auth_oidc_fr_html_829eaa34e529ef0c.png?width=72&height=72&rev=1.1\|\|alt="config_auth_oidc_fr_html_829eaa34e529ef0c.png"]]
	212	\|(((
	213	This parameter can be edited via the web.xml file as indicated above. This file is specific to each installation of DigDash. You can enter this parameter more generally in the file
22.1	214
73.1	215	(% style="background-color:transparent" %)<user> / Application Data / Enterprise Server / dashboard_system.xml
	216
22.1	217	(((
73.1	218	For more information, you can refer to the DigDash documentation “guide_avance_systeme_fr.pdf”.
22.1	219	)))
73.1	220	)))
22.1	221
73.1	222	== Changing the value of the sharedPasswd parameter ==
22.1	223
73.1	224	Change the value of the //sharedPasswd// parameter (secret value below to change) in the web.xml file of Dashboard in the folders
22.1	225
73.1	226	<digdash_installation>/apache-tomcat/webapps/digdash_dashboard/WEB-INF
22.1	227
73.1	228	and
22.1	229
73.1	230	<digdash_installation>/apache-tomcat/webapps/studio/WEB-INF
	231
	232	The value must correspond to that mentioned in the //sharedPasswd// attribute in the valve of the file
	233
	234	<digdash_installation>/apache-tomcat/conf/server.xml (see part II.2).
	235
	236	{{code cssClass="notranslate"}}
	237	<web-app ... >
	238	...
	239	<servlet>
	240	<servlet-name>dashServlet</servlet-name>
	241	<servlet-class>com.digdash.server.DigdashServiceImpl</servlet-class>
	242	...
	243	<init-param>
	244	<param-name>sharedPasswd</param-name>
	245	<param-value>secret</param-value>
	246	</init-param>
	247	...
	248	</servlet>
	249	...
	250	</web-app>
32.1	251	{{/code}}
22.1	252
73.1	253	__Extract from the server.xml file__
64.1	254
73.1	255	Value for parameter sharedPasswd is variable according to the installation.
22.1	256
73.1	257	== Modification of the authentication method ==
1.1	258
73.1	259	Modify the authentication method (LDAP is the default method) in the web.xml file located in the folder
1.1	260
73.1	261	<digdash_installation>/apache-tomcat/webapps/ddenterpriseapi/WEB-INF .
1.1	262
73.1	263	"External" means that safety is managed by the valve configured above.
1.1	264
73.1	265	{{code language="XML" cssClass="notranslate"}}
	266	<web-app ... >
	267	...
	268	<servlet>
	269	...
	270	</servlet>
	271	...
	272	<servlet>
	273	<description></description>
	274	<display-name>DDEnterpriseAuthServlet</display-name>
	275	<servlet-name>DDEnterpriseAuthServlet</servlet-name>
	276	<servlet-class> com.digdash.server.DDEnterpriseAuthServlet</servlet-class>
	277	<init-param>
	278	<param-name>authMethod</param-name>
	279	<param-value>External</param-value>
	280	</init-param>
	281	...
	282	</servlet>
	283	...
	284	</web-app>
	285	{{/code}}
1.1	286
73.1	287	__Extract from web.xml file__
1.1	288
73.1	289	= OpenID Provider configuration =
1.1	290
73.1	291	The OP must register DigDash as a RP in its list of RPs for DigDash to be able to take advantage of Single Sign-On.
1.1	292
73.1	293	Also, the OP will have to enter the callback URL to identify the entry point of the DigDash application. The URL will be of the form
1.1	294
73.1	295	https:~/~/<IP address>:<port>/digdash_oidc_endpoint/oidcendpoint
37.1	296
73.1	297	= Log level =
48.1	298
73.1	299	You can customize the log level for the authentication valve.
48.1	300
73.1	301	By default, only errors are logged. If however you want to have more details on the course of actions and exchanges between the different entities, you can assign the value 'DEBUG' instead of 'ERROR' in the log4j.properties file which was imported into the lib folder of Tomcat .
48.1	302
73.1	303	log4j.logger.org.bsworks = ERROR , stdout
48.1	304
73.1	305	log4j.logger.org.bsworks = DEBUG , stdout
48.1	306
73.1	307	= OpenID Connect authentication on the Enterprise Studio side =
48.1	308
73.1	309	To authenticate with OpenID Connect on the Enterprise Studio side, please ensure that you have performed the following actions:
	310
	311	== Server and domain definitions in the .jnlp file ==
	312
	313	You can, like the Dashboard, define the server and the domain on which DigDash will rely.
	314
	315	To do this, modify the end of the digdash.jnlp file in the DigDash installation folder <digdash_installation> / apache-tomcat / webapps / adminconsole
	316
	317	{{code cssClass="notranslate"}}
	318	<jnlp ...>
	319	...
	320	<application-desc main-class="commandline.CommandLineMain">
	321	<argument>https://localhost:8443</argument> (1)
	322	<argument>ddenterpriseapi</argument> (2)
	323	<argument><%=lang%></argument> (3)
	324	<argument><%=dashboard%></argument> (4)
	325	<argument>-AuthMode=External</argument> (5)
	326	<argument>-SSLNoPathCheck</argument> (A)
	327	...
	328	</application-desc>
	329	</jnlp>
48.1	330	{{/code}}
	331
73.1	332	__Extract from the digdash.jnlp file__
48.1	333
73.1	334	__Warning__ : the arguments noted (1), (2), (3), (4), (5) must not change order.
48.1	335
73.1	336	Argument (1): the address of the DigDash server; variable depending on your installation
48.1	337
73.1	338	Argument (2): the name of the DigDash domain; variable depending on your installation
48.1	339
73.1	340	Argument (5): The authentication method; External, mandatory
48.1	341
73.1	342	Argument (A): optional argument, sometimes necessary in the case of SSL, HTTPS connections.
48.1	343
73.1	344	== Connection to DigDash Enterprise Studio ==
48.1	345
73.1	346	Download and run the .jnlp by going to the DigDash home page in the Enterprise Studio section.
48.1	347
73.1	348	[[image:1592471261704-499.png\|\|queryString="width=622&height=306" height="306" width="622"]]
48.1	349
73.1	350	An authentication window should appear with the IdP authentication target.
48.1	351
73.1	352	In this document, Google is the OP that we have chosen to illustrate our examples.
52.1	353
73.1	354	[[image:http://rack-lure:8585/bin/download/Digdash_2019R2/others_documents/config_auth_oidc/WebHome/config_auth_oidc_fr_html_4273fd0e30eb8463.png?width=632&height=388&rev=1.1\|\|alt="config_auth_oidc_fr_html_4273fd0e30eb8463.png"]]
	355	\\
52.1	356
73.1	357	__Capture: test pattern with Google OP authentication form__
1.1	358
73.1	359	The user will have to enter his connection data and if he has been authenticated with the OP and that he corresponds to an existing user in the LDAP DigDash, the authentication will have succeeded and the window will attest to the success of the authentication.
1.1	360
73.1	361	[[image:http://rack-lure:8585/bin/download/Digdash_2019R2/others_documents/config_auth_oidc/WebHome/config_auth_oidc_fr_html_6230a5f637fd4c54.png?width=608&height=372&rev=1.1\|\|alt="config_auth_oidc_fr_html_6230a5f637fd4c54.png"]]
	362	\\
14.1	363
73.1	364	__Capture: window of successful authentication__
1.1	365
73.1	366	The window will close automatically, then Enterprise Studio will start loading to launch.
1.1	367
73.1	368	= Lexicon =
1.1	369
73.1	370	We will call in this document:
1.1	371
73.1	372	* SSO: Single Sign On or Single Authentication; OpenIDConnect is an SSO method
	373	* OP: OpenID Provider or the Identity Provider
	374	* PR: the Relying Party or the Service Provider (DigDash)
	375	* Endpoint: Entry point
	376
	377	= References =
	378
	379	https:~/~/www.oasis-open.org
	380
	381	//DigDash uses the OpenSource tomcat8-oidcauth library from Boyle Software, Inc. to support the OpenID Connect authentication method.//
	382
	383	https:~/~/www.boylesoftware.com/
	384
	385	https:~/~/github.com/boylesoftware/tomcat8-oidcauth
	386

Wiki source code of Authentification OpenID Connect

Sommaire