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

Wiki source code of Single sign-on NTLM

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

version	line-number	content
1.1	1	{{ddtoc/}}
	2
	3	----
	4
33.1	5	This document describes how to connect the Waffle valve in DigDash Enterprise to active Windows Integrated Security (NTLM...).
1.1	6
33.1	7	This add-on is located in <DDE install>/add-ons/singlesignon/Waffle.
1.1	8
33.1	9	The current Waffle version is 1.8.1.
1.1	10
33.1	11	This document describes all folders and files to modifiy to activate this valve.
1.1	12
33.1	13	= apache-tomcat / lib =
5.1	14
33.1	15	__Cleanup previous waffle version__
26.1	16
33.1	17	In case of a DigDash upgrade, you may have a previous version of waffle deployed on the tomcat. You must first clean the corresponding jar files from <DDE install>/apache-tomcat/lib. Please refer to the waffle deployment guide from the previous version of DigDash to delete the old waffle library files from <DDE install>/apache-tomcat/lib, and only these ones.
26.1	18
33.1	19	__Tomcat 9 (from version 2020R2 patch 20210105)__
1.1	20
33.1	21	Add the waffle libraries from the folder <DDE install>/add-ons/singlesignon/Waffle/Tomcat9 to the folder <DDE install>/apache-tomcat/lib:
1.1	22
33.1	23	* caffeine-2.8.4.jar
3.1	24	* guava-19.0.jar
	25	* jna-5.6.0.jar
	26	* jna-platform-5.6.0.jar
	27	* slf4j-api-1.7.21.jar
	28	* slf4j-log4j12-1.7.21.jar
	29	* log4j-1.2.15.jar
	30	* waffle-jna-2.3.0.jar
	31	* waffle-tomcat9-2.3.0.jar
	32	* waffle_digdash_extension_tomcat9.jar
	33	* log4j.properties
	34
33.1	35	__Tomcat 8__
1.1	36
33.1	37	Add the waffle libraries from the folder <DDE install>/add-ons/singlesignon/Waffle/Tomcat8 to the folder <DDE install>/apache-tomcat/lib:
26.1	38
33.1	39	* guava-19.0.jar
	40	* jna-4.2.1.jar
	41	* jna-platform-4.2.1.jar
	42	* slf4j-api-1.7.21.jar
	43	* slf4j-log4j12-1.7.21.jar
	44	* log4j-1.2.15.jar
	45	* waffle-jna-1.8.1.jar
	46	* waffle-tomcat8-1.8.1.jar
	47	* waffle_digdash_extension_tomcat8.jar
	48	* log4j.properties
26.1	49
33.1	50	__Tomcat 7__
2.1	51
33.1	52	Add the waffle libraries from the folder <DDE install>/add-ons/singlesignon/Waffle/Tomcat7 to the folder <DDE install>/apache-tomcat/lib:
1.1	53
33.1	54	* guava-19.0.jar
	55	* jna-4.2.1.jar
	56	* jna-platform-4.2.1.jar
	57	* slf4j-api-1.7.21.jar
	58	* slf4j-log4j12-1.7.21.jar
	59	* log4j-1.2.15.jar
	60	* waffle-jna-1.8.1.jar
	61	* waffle-tomcat7-1.8.1.jar
	62	* waffle_digdash_extension_tomcat7.jar
	63	* log4j.properties
2.1	64
33.1	65	= apache-tomcat / conf / context.xml =
7.2	66
33.1	67	Add the following security valve XML:
1.1	68
33.1	69	<Valve className="waffle.apache.SharedNegotiateAuthenticator" principalFormat="fqn" roleFormat="both" sharedPasswd="SecretPwdToChange" allowAddr="localhost,127.0.0.*"/>
32.1	70
33.1	71	<Realm className="waffle.apache.WindowsRealm"/>
1.1	72
33.1	73	It is important to change the shared password (sharedPasswd). This password must be identical to the one specified in file <DDE install>/apache-tomcat/digdash_dashboard/WEB-INF/web.xml (see chapter IV).
26.1	74
33.1	75	You can also add allowed remote host addresses (allowAddr) to let other applications (digdash_dashboard) to connect to DigDash Enterprise server. In allowAddr attribute, you should add your server's IP address.
26.1	76
33.1	77	= apache-tomcat / conf / web.xml =
1.1	78
33.1	79	Add the XML content for the security constraint:
	80
	81	{{code language="XML" cssClass="notranslate"}}
1.1	82	<security-role>
33.1	83	<role-name>Everyone</role-name>
1.1	84	</security-role>
33.1	85
1.1	86	<security-constraint>
33.1	87	<display-name>Waffle Security Constraint</display-name>
	88	<web-resource-collection>
	89	<web-resource-name>Protected Area</web-resource-name>
	90	<url-pattern>/*</url-pattern>
	91	</web-resource-collection>
	92	<auth-constraint>
	93	<role-name>Everyone</role-name>
	94	</auth-constraint>
1.1	95	</security-constraint>
33.1	96
1.1	97	<security-constraint>
33.1	98	<display-name>vjdbc Security Constraint</display-name>
	99	<web-resource-collection>
	100	<web-resource-name>UnProtected Area</web-resource-name>
	101	<url-pattern>/vjdbc/*</url-pattern>
	102	</web-resource-collection>
1.1	103	</security-constraint>
	104	{{/code}}
	105
33.1	106	//Important//
20.1	107
1.1	108	(% class="box warningmessage" %)
	109	(((
33.1	110	Security role name (role-name) MUST match the actual role you have in your AD (localized). Example : BUILTIN\Users
1.1	111	)))
	112
33.1	113	If your are not sure about the role names in your Active Directory, you can activate the debug log for waffle by using the provided log4j.properties. You just need to copy this file into <DDE install>/apache-tomcat/lib
1.1	114
33.1	115	= apache-tomcat / webapps / digdash_dashboard / WEB-INF / web.xml =
1.1	116
33.1	117	Search for the definition of the parameter sharedPasswd in this file, un-comment the corresponding XML and change the password value (__bold underline__):
29.1	118
33.1	119	{{code language="XML" cssClass="notranslate"}}
	120	<init-param>
	121	<param-name>sharedPasswd</param-name>
	122	<param-value>SecretPwdToChange</param-value>
	123	</init-param>
	124	{{/code}}
4.2	125
33.1	126	//Important//
4.2	127
33.1	128	(% class="box warningmessage" %)
	129	(((
	130	The specified password must be identical to the one set in file <DDE install>/apache-tomcat/conf/context.xml (chapter II).
	131	)))
4.2	132
33.1	133	(% class="wikigeneratedid" id="HRecommendedparametersforautomaticloginindashboard" %)
	134	__Recommended parameters for automatic login in dashboard__
4.2	135
33.1	136	It is recommended to configure the following parameters in file <DDE install>/apache-tomcat/webapps/digdash_dashboard/WEB-INF/web.xml when deploying for using Windows Integrated Security (Waffle).
4.2	137
33.1	138	Specify (and force) DigDash Enterprise domain:
6.6	139
33.1	140	{{code cssClass="notranslate"}}
	141	<init-param>
	142	<param-name>DOMAIN</param-name>
	143	<param-value>ddenterpriseapi</param-value>
	144	</init-param>
	145	<init-param>
	146	<param-name>FORCEDOMAIN</param-name>
	147	<param-value>true</param-value>
	148	</init-param>
	149
6.6	150	{{/code}}
	151
33.1	152	Specify (and force) DigDash Enterprise domain URL. Use localhost address when ddenterpriseapi web application is installed on the same Tomcat than digdash_dashboard web application. Adapt port if needed:
6.6	153
33.1	154	{{code language="XML" cssClass="notranslate"}}
	155	<init-param>
	156	<param-name>SERVERURL</param-name>
	157	<param-value>http://localhost:8080</param-value>
	158	</init-param>
	159	<init-param>
	160	<param-name>FORCESERVERURL</param-name>
	161	<param-value>true</param-value>
	162	</init-param>
	163	{{/code}}
6.6	164
33.1	165	Specify a logout URL to allow the user to disconnect properly from DigDash Enterprise and, for example, return to an Intranet page:
6.6	166
33.1	167	{{code language="XML" cssClass="notranslate"}}
	168	<init-param>
	169	<param-name>urlLogout</param-name>
	170	<param-value>/adminconsole</param-value>
	171	</init-param>
	172	{{/code}}
6.6	173
33.1	174	//Important//
4.2	175
33.1	176	(% class="box warningmessage" %)
	177	(((
	178	By default, loging out the dashboard returns to its login page. This page is bypassed in a SSO context, so it automatically logs in the user again. It is important to specify a logout page to create a nice user experience.
	179	)))
4.2	180
33.1	181	See the document digdash_enterprise_advanced_system_guide_en.pdf for more details on these parameters.
6.2	182
33.1	183	= apache-tomcat / webapps / studio / WEB-INF / web.xml =
	184
	185	Search for the definition of the parameter sharedPasswd in this file, un-comment the corresponding XML and change the password value (__bold underline__):
	186
	187	{{code language="XML" cssClass="notranslate"}}
	188	<init-param>
	189	<param-name>sharedPasswd</param-name>
	190	<param-value>SecretPwdToChange</param-value>
	191	</init-param>
1.1	192	{{/code}}
	193
33.1	194	//Important//
	195
1.1	196	(% class="box warningmessage" %)
	197	(((
33.1	198	The specified password must be identical to the one set in file <DDE install>/apache-tomcat/conf/context.xml (chapter II).
1.1	199	)))
	200
33.1	201	(% class="wikigeneratedid" id="HRecommendedparametersforautomaticloginindashboard" %)
	202	__Recommended parameters for automatic login in studio__
1.1	203
33.1	204	It is recommended to configure the following parameters in file <DDE install>/apache-tomcat/webapps/studio/WEB-INF/web.xml when deploying for using Windows Integrated Security (Waffle).
1.1	205
33.1	206	Specify (and force) DigDash Enterprise domain:
1.1	207
33.1	208	{{code cssClass="notranslate"}}
	209	<init-param>
	210	<param-name>DOMAIN</param-name>
	211	<param-value>ddenterpriseapi</param-value>
	212	</init-param>
	213	<init-param>
	214	<param-name>FORCEDOMAIN</param-name>
	215	<param-value>true</param-value>
	216	</init-param>
1.1	217
	218	{{/code}}
	219
33.1	220	Specify (and force) DigDash Enterprise domain URL. Use localhost address when ddenterpriseapi web application is installed on the same Tomcat than studio web application. Adapt port if needed:
1.1	221
33.1	222	{{code language="XML" cssClass="notranslate"}}
	223	<init-param>
	224	<param-name>SERVERURL</param-name>
	225	<param-value>http://localhost:8080</param-value>
	226	</init-param>
	227	<init-param>
	228	<param-name>FORCESERVERURL</param-name>
	229	<param-value>true</param-value>
	230	</init-param>
1.1	231	{{/code}}
	232
33.1	233	Specify a logout URL to allow the user to disconnect properly from DigDash Enterprise and, for example, return to an Intranet page:
1.1	234
33.1	235	{{code language="XML" cssClass="notranslate"}}
	236	<init-param>
	237	<param-name>urlLogout</param-name>
	238	<param-value>/adminconsole</param-value>
	239	</init-param>
1.1	240	{{/code}}
	241
33.1	242	//Important//
1.1	243
	244	(% class="box warningmessage" %)
	245	(((
33.1	246	By default, loging out the studio returns to its login page. This page is bypassed in a SSO context, so it automatically logs in the user again. It is important to specify a logout page to create a nice user experience.
1.1	247	)))
	248
33.1	249	See the document digdash_enterprise_advanced_system_guide_en.pdf for more details on these parameters.
1.1	250
33.1	251	= apache-tomcat / webapps / ddenterpriseapi / WEB-INF / web.xml =
6.3	252
33.1	253	Search for definition of the authMethod parameter in this file and change its value into NTUser:
6.3	254
33.1	255	{{code cssClass="notranslate"}}
	256	<init-param>
	257	<param-name>authMethod</param-name>
	258	<!-- possible values: LDAP, PassThru, NTUser, NTUserOrLDAP -->
	259	<param-value>NTUser</param-value>
	260	</init-param>
7.3	261	{{/code}}
	262
33.1	263	//Note//
6.3	264
33.1	265	(% class="box infomessage" %)
1.1	266	(((
33.1	267	The mode « NTUserOrLDAP » let the user authenticate on the DigDash server through Windows Integrated Security, with a fallback authentication through DigDash LDAP.
1.1	268	)))
	269
33.1	270	For instance, a user from the NT domain could automatically pass the Waffle valve with his Windows credentials, but would fail loging in DigDash if he does not exist in DigDash LDAP. In that mode, he would get a login form to specify a DigDash login/password.
1.1	271
33.1	272	Also in this mode is an optional parameter « loginForm » used in some URLs which allows the login page to be always displayed. This way the Windows credentials are only used to pass the Waffle valve. A typical use case is to allow a Windows user to connect as “admin” in DigDash settings pages.
1.1	273
33.1	274	= apache-tomcat / webapps / adminconsole / digdash.jnlp =
1.1	275
33.1	276	{{warning}}
	277	We would rather use the Web Studio from version 2020R2.
	278	{{/warning}}
1.1	279
33.1	280	By default, when the DigDash server is configured to use the Windows Integrated Security, the user must enter its Windows login (NT domain\user) and password in the Studio login dialog box. For instance:
1.1	281
33.1	282	User: NT_DOMAIN\user1
1.1	283
33.1	284	Password: ~~~~~~
1.1	285
33.1	286	There is a way to allow the Studio to automatically authenticate the current logged Windows user. The following conditions are required:
1.1	287
33.1	288	* Studio is launched on a Windows computer, from a Windows session authenticated in the concerned Windows security domain
	289	* The URL of the DigDash server, the DigDash enterprise domain name, and the authentication mode of the Studio (NTUser, NTUserOrLDAP…) are specified and forced in the JNLP file
	290
	291	Proceed with the following configuration in the <DDE install>/apache-tomcat/webapps/adminconsole/digdash.jnlp file if you want to activate the automatic login with Windows Integrated Security in DigDash Enterprise Studio.
	292
	293	At the end of this file you will find the XML for the parameter of the Studio. Replace the value of some of the parameters as shown below (see values in __bold underline__):
	294
	295	{{code language="XML" cssClass="notranslate"}}
	296	<application-desc main-class="commandline.CommandLineMain">
	297	<argument>http://server_digdash:8080</argument>
	298	<argument>ddenterpriseapi</argument>
	299	<argument><%=lang%></argument>
	300	<argument><%=dashboard%></argument>
	301	<argument>true</argument>
	302	<argument>NTUser</argument>
	303	</application-desc>
1.1	304	{{/code}}
	305
33.1	306	Description of the modified parameters:
	307
	308	* 1^^st^^ parameter: DigDash serveur URL accessed by the Studio.
	309	* 2^^nd^^ parameter: DigDash Enterprise domain name.
	310	* 5^^th^^ parameter: Force specified URL and domaine name: they are read-only in Studio’s login dialog box (true).
	311	* 6^^th^^ parameter: Forced authentication mode for the Studio (see chapter V for more details). Only the « NTUser », « NTUserOrLDAP » or « NTUserOrLDAP,loginForm » allow the automatic login with Windows Integrated Security.

Wiki source code of Single sign-on NTLM

Sommaire