Last modified by Aurelie Bertrand on 2026/01/12 16:46
Show last authors
1 {{ddtoc/}}
2
3 ----
4
5 (% class="wikigeneratedid" %)
6 This document describes how to set up a custom authentication valve for DigDash Enterprise.
7
8 = Prerequisites =
9
10 * Have the **<Install DD>/add-ons/CustomAuthenticator** folder containing all the files needed to set up the custom authentication valve in the DigDash Tomcat server. The placement of these files is described in this document.
11 * The following operations must be carried out **with the DigDash server stopped**.
12
13 = Configuring the DigDash server =
14
15 == Copy the libraries ==
16
17 Copy the libraries and the log configuration file from the **<install DD>/add-ons/CustomAuthenticator/tomcat** folder to the :
18
19 (% class="box" %)
20 (((
21 * under Linux: **/usr/share/tomcat9/lib/**
22 * under Windows: **C:\Program Files\Apache Software Foundation\Tomcat 9.0\lib**
23 )))
24
25 Files to copy :
26
27 * commons-codec-1.15.jar
28 * commons-logging-1.2.jar
29 * custom_authenticator.jar
30 * httpclient-4.5.5.jar
31 * httpcore-4.4.9.jar
32 * httpmime-4.5.5.jar
33 * log4j-1.2-api-2.19.0.jar
34 * log4j-api-2.19.0.jar
35 * log4j-core-2.19.0.jar
36
37 == Adding the custom authentication valve ==
38
39 Activate the custom authentication valve in the **context.xml** file located in the :
40
41 (% class="box" %)
42 (((
43 * on Linux: **/etc/tomcat9/context.xml**
44 * under Windows: **C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf**
45 )))
46
47 To do this, look for the **<Context ...>** element in the file, uncomment or add the **<Valve ...>** element below:
48
49 (((
50 {{code language="XML" cssClass="notranslate"}}
51 <Valve className="custom.apache.CustomAuthenticator"
52 sharedPasswd="secret"
53 allowAddr=".*localhost.*,.*127.0.0.*"
54 portalUrl="<url>?login=${login}&amp;token=${token}"
55 fallbackAuth="LDAP"
56 expectedResponse="OK" />
57 {{/code}}
58
59 Legend: (% style="color:#c0392b" %)//invariable value//(%%)// / (% style="color:#27ae60" %)variable value depending on installation//
60 )))
61
62 |(% style="width:238px" %)**Attribute**|(% style="width:1181px" %)**Description**
63 |(% style="color:#c0392b; width:238px" %)className|(% style="width:1181px" %)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 in fact several implementations provided by Tomcat.
64 |(% style="color:#27ae60; width:238px" %)sharedPasswd|(% style="width:1181px" %)The shared password checked during authentication (see point II.5).
65 |(% style="color:#27ae60; width:238px" %)allowAddr|(% style="width:1181px" %)Regular expression(s) that the address used to send requests to the dashboard must satisfy. In the case of multiple regexes, separate with commas.
66 |(% style="color:#27ae60; width:238px" %)portalUrl|(% style="width:1181px" %)(((
67 The address of the user and token verification page.
68
69 - It can be unique and request validation from a single server; in this case:
70
71 (% style="color:#27ae60" %)<protocol>:~/~/<host>:<port>/<context>/<path(% style="color:#c0392b" %)>?login=${login}&amp;token=${token}
72
73 - It may correspond to the address of the source sending the access request to the dashboard; in this case, indicate only the remaining path:
74
75 (% style="color:#27ae60" %)<context>/<path(% style="color:#c0392b" %)>?login=${login}&amp;token=${token}
76
77 The valve will analyse the Referer to which to send the verification request in the header parameters of the incoming request.
78 )))
79 |(% style="color:#27ae60; width:238px" %)fallbackAuth|(% style="width:1181px" %)Authentication method to use if the valve's authentication fails.
80 |(% style="color:#27ae60; width:238px" %)expectedResponse|(% style="width:1181px" %)Response returned by the page in the event of valid authentication (not case-sensitive), all other responses lead to authentication failure.
81 |(%%)(% style="color:#27ae60" %)excludedPaths|//Optional,// these are the regular expressions of the paths whose resources are authorised to pass the valve, thereby switching to LDAP authentication mode. Example: "/.*"
82 |(% style="color:#27ae60; width:238px" %)print_debug|(% style="width:1181px" %)Optional, set to false by default, otherwise add print_debug=(% style="color:#27ae60" %)"true(%%)" for more verbose traces.
83
84 == Adding security constraints ==
85
86 Uncomment or add the security constraints to the **web.xml** file located in the :
87
88 (% class="box" %)
89 (((
90 * under Linux: **/etc/tomcat9/**
91 * under Windows : **C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf**
92 )))
93
94 {{code language="XML" cssClass="notranslate"}}
95 <web-app ...>
96 ...
97 <security-role>
98 <role-name>CUSTOM</role-name>
99 </security-role>
100
101 <security-constraint>
102 <display-name>CUSTOM Security Constraint</display-name>
103 <web-resource-collection>
104 <web-resource-name>Protected Area</web-resource-name>
105 <url-pattern>/*</url-pattern>
106 </web-resource-collection>
107 <auth-constraint>
108 <role-name>CUSTOM</role-name>
109 </auth-constraint>
110 </security-constraint>
111
112 <security-constraint>
113 <web-resource-collection>
114 <web-resource-name>Non-Protected Area</web-resource-name>
115 <url-pattern>/vjdbc</url-pattern>
116 </web-resource-collection>
117 </security-constraint>
118 ...
119 </web-app>
120 {{/code}}
121
122 (((
123
124 = Application configuration =
125
126 To do this, modify the **digdash.properties** file in **<install DD> **or** /etc/digdash** or in the folder you have configured.
127
128
129 == Server configuration (ddenterprise.war) ==
130
131 In the **digdash.properties** file:
132
133 In the //ddenterpriseapi.war// box, find and uncomment the following lines with the values shown:
134
135 {{code language="properties" cssClass="notranslate"}}
136 ddenterpriseapi.authMethod=External
137 {{/code}}
138
139
140 == Dashboard configuration (digdash_dashboard.war) ==
141
142 In the **digdash.properties** file :
143
144 In the //digdash_dashbord.war// box, find and uncomment the following lines with the values shown:
145
146 {{code language="properties" cssClass="notranslate"}}
147 digdash_dashboard.SERVERURL=http://localhost:8080
148 digdash_dashboard.DOMAIN=ddenterpriseapi
149 digdash_dashboard.FORCEDOMAIN=true
150 digdash_dashboard.FORCESERVERURL=true
151 digdash_dashboard.sharedPasswd=<la valeur de l'attribut sharedPasswd dans l'élément Valve>
152 {{/code}}
153
154 (% class="box infomessage" %)
155 (((
156 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.
157 )))
158
159
160 == Studio configuration (studio.war) ==
161
162 In the **digdash.properties** file :
163
164 In the //studio.war// box, find and uncomment the following lines with the values shown:
165
166 {{code language="properties" cssClass="notranslate"}}
167 studio.SERVERURL=http://localhost:8080
168 studio.DOMAIN=ddenterpriseapi
169 studio.FORCEDOMAIN=true
170 studio.FORCESERVERURL=true
171 studio.PUBLICSERVERURL=<votre adresse URL publique>
172 studio.sharedPasswd=<la valeur de l'attribut sharedPasswd dans l'élément Valve>
173 {{/code}}
174
175 (% class="box infomessage" %)
176 (((
177 The example value for the parameter //studio.SERVERURL// 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.
178 )))
179 )))