Wiki source code of Single sign-on NTLM

Last modified by mperroud on 2021/03/29 06:27

Show last authors
1 {{ddtoc/}}
2
3 ----
4
5 This document describes how to connect the Waffle valve in DigDash Enterprise to active Windows Integrated Security (NTLM...).
6
7 This add-on is located in **<DDE install>/add-ons/singlesignon/Waffle**.
8
9 The current Waffle version is 1.8.1.
10
11 This document describes all folders and files to modifiy to activate this valve.
12
13 = apache-tomcat / lib =
14
15 __**Cleanup previous waffle version**__
16
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.
18
19 __**Tomcat 9 (from version 2020R2 patch 20210105)**__
20
21 Add the waffle libraries from the folder **<DDE install>/add-ons/singlesignon/Waffle/Tomcat9** to the folder **<DDE install>/apache-tomcat/lib**:
22
23 * caffeine-2.8.4.jar
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
35 __**Tomcat 8**__
36
37 Add the waffle libraries from the folder **<DDE install>/add-ons/singlesignon/Waffle/Tomcat8** to the folder **<DDE install>/apache-tomcat/lib**:
38
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
49
50 __**Tomcat 7**__
51
52 Add the waffle libraries from the folder **<DDE install>/add-ons/singlesignon/Waffle/Tomcat7** to the folder **<DDE install>/apache-tomcat/lib**:
53
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
64
65 = apache-tomcat / conf / context.xml =
66
67 Add the following security valve XML:
68
69 <Valve className="waffle.apache.SharedNegotiateAuthenticator" principalFormat="fqn" roleFormat="both" **sharedPasswd**="**SecretPwdToChange**" **allowAddr**="**localhost,127.0.0.***"/>
70
71 <Realm className="waffle.apache.WindowsRealm"/>
72
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).
74
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.
76
77 = apache-tomcat / conf / web.xml =
78
79 Add the XML content for the security constraint:
80
81 {{code language="XML"}}
82 <security-role>
83 <role-name>Everyone</role-name>
84 </security-role>
85
86 <security-constraint>
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>
95 </security-constraint>
96
97 <security-constraint>
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>
103 </security-constraint>
104 {{/code}}
105
106 //Important//
107
108 (% class="box warningmessage" %)
109 (((
110 Security role name (role-name) MUST match the actual role you have in your AD (localized). Example : BUILTIN\Users
111 )))
112
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**
114
115 = apache-tomcat / webapps / digdash_dashboard / WEB-INF / web.xml =
116
117 Search for the definition of the parameter **sharedPasswd** in this file, un-comment the corresponding XML and change the password value (__**bold underline**__):
118
119 {{code language="XML"}}
120 <init-param>
121 <param-name>sharedPasswd</param-name>
122 <param-value>SecretPwdToChange</param-value>
123 </init-param>
124 {{/code}}
125
126 //Important//
127
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 )))
132
133 (% class="wikigeneratedid" id="HRecommendedparametersforautomaticloginindashboard" %)
134 __Recommended parameters for automatic login in dashboard__
135
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).
137
138 Specify (and force) DigDash Enterprise domain:
139
140 {{code}}
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
150 {{/code}}
151
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:
153
154 {{code language="XML"}}
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}}
164
165 Specify a logout URL to allow the user to disconnect properly from DigDash Enterprise and, for example, return to an Intranet page:
166
167 {{code language="XML"}}
168 <init-param>
169 <param-name>urlLogout</param-name>
170 <param-value>/adminconsole</param-value>
171 </init-param>
172 {{/code}}
173
174 //Important//
175
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 )))
180
181 See the document **digdash_enterprise_advanced_system_guide_en.pdf** for more details on these parameters.
182
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"}}
188 <init-param>
189 <param-name>sharedPasswd</param-name>
190 <param-value>SecretPwdToChange</param-value>
191 </init-param>
192 {{/code}}
193
194
195 (% class="box warningmessage" %)
196 (((
197 The specified password must be identical to the one set in file **<DDE install>/apache-tomcat/conf/context.xml** (chapter II).
198 )))
199
200
201 (% id="cke_bm_209S" style="display:none" %) (%%)Search for the definition of the parameter **authMethod** in this file, un-comment the corresponding XML:
202
203 {{code language="XML"}}
204 <init-param>
205 <param-name>authMethod</param-name>
206 <param-value>NTUserOrLDAP</param-value>
207 </init-param>
208 {{/code}}
209
210
211 (% class="wikigeneratedid" id="HRecommendedparametersforautomaticloginindashboard" %)
212 __Recommended parameters for automatic login in studio__
213
214 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).
215
216 Specify (and force) DigDash Enterprise domain:
217
218 {{code}}
219 <init-param>
220 <param-name>DOMAIN</param-name>
221 <param-value>ddenterpriseapi</param-value>
222 </init-param>
223 <init-param>
224 <param-name>FORCEDOMAIN</param-name>
225 <param-value>true</param-value>
226 </init-param>
227
228 {{/code}}
229
230 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:
231
232 {{code language="XML"}}
233 <init-param>
234 <param-name>SERVERURL</param-name>
235 <param-value>http://localhost:8080</param-value>
236 </init-param>
237 <init-param>
238 <param-name>FORCESERVERURL</param-name>
239 <param-value>true</param-value>
240 </init-param>
241 {{/code}}
242
243 Specify a logout URL to allow the user to disconnect properly from DigDash Enterprise and, for example, return to an Intranet page:
244
245 {{code language="XML"}}
246 <init-param>
247 <param-name>urlLogout</param-name>
248 <param-value>/adminconsole</param-value>
249 </init-param>
250 {{/code}}
251
252 //Important//
253
254 (% class="box warningmessage" %)
255 (((
256 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.
257 )))
258
259 See the document **digdash_enterprise_advanced_system_guide_en.pdf** for more details on these parameters.
260
261 = apache-tomcat / webapps / ddenterpriseapi / WEB-INF / web.xml =
262
263 Search for definition of the **authMethod** parameter in this file and change its value into **NTUser**:
264
265 {{code}}
266 <init-param>
267 <param-name>authMethod</param-name>
268 <!-- possible values: LDAP, PassThru, NTUser, NTUserOrLDAP -->
269 <param-value>NTUser</param-value>
270 </init-param>
271 {{/code}}
272
273 //Note//
274
275 (% class="box infomessage" %)
276 (((
277 The mode «** NTUserOrLDAP **» let the user authenticate on the DigDash server through Windows Integrated Security, with a fallback authentication through DigDash LDAP.
278 )))
279
280 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.
281
282 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.
283
284 = apache-tomcat / webapps / adminconsole / digdash.jnlp =
285
286 {{warning}}
287 We would rather use the Web Studio from version 2020R2.
288 {{/warning}}
289
290 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:
291
292 User: NT_DOMAIN\user1
293
294 Password: ~*~*~*~*~*~*
295
296 There is a way to allow the Studio to automatically authenticate the current logged Windows user. The following conditions are required:
297
298 * Studio is launched on a Windows computer, from a Windows session authenticated in the concerned Windows security domain
299 * 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
300
301 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.
302
303 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**__):
304
305 {{code language="XML"}}
306 <application-desc main-class="commandline.CommandLineMain">
307 <argument>http://server_digdash:8080</argument>
308 <argument>ddenterpriseapi</argument>
309 <argument><%=lang%></argument>
310 <argument><%=dashboard%></argument>
311 <argument>true</argument>
312 <argument>NTUser</argument>
313 </application-desc>
314 {{/code}}
315
316 Description of the modified parameters:
317
318 * 1^^st^^ parameter: DigDash serveur URL accessed by the Studio.
319 * 2^^nd^^ parameter: DigDash Enterprise domain name.
320 * 5^^th^^ parameter: Force specified URL and domaine name: they are read-only in Studio’s login dialog box (true).
321 * 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.