OpenID Connect authentication

* 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 .

18

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.**//

21

22

= Configuration of the DigDash server =

23

24

== Copy of libraries ==

25

26

Add the libraries and the log configuration file from the **apache-tomcat / lib** folder to the folder

27

28

**<digdash_installation> / apache / lib** :

29

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|

33

34

__Libraries in the apache-tomcat/lib folder__

35

36

== Addition of the OpenID Connect authentication valve ==

37

38

Add the OpenID Connect authentication valve in the **server.xml** file located in the folder

39

40

<digdash_installation>/apache-tomcat/conf

41

42

To do this, add the following Valve element in the **Host** element .

...

<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="[

53

{

54

name: OpenID Provider name,

55

issuer: issuer,

56

clientId: clientId,

57

clientSecret: clientSecret

58

}

59

]"

60

usernameClaim="email"

61

additionalScopes="email"

></Valve>

...

</Host>

...

</Server>

__Extract from the server.xml file__

70

71

Value for parameter className is invariable.

72

Values for parameters allowAddr, sharedPasswd, redirect_url, providers, usernameClaim, additionalScopes are variable according to the installation.

73

74

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.

84

85

Example: cookieTimeOut = "3600" (1 hour)

86

)))

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.

90

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:

92

93

- **issuer **//(mandatory) // : This is the only one with a unique URL to identify the OP.

94

95

- **name **//(optional) // : A name associated with the PO; if not by default.

96

97

(((

98

- **clientId **//(mandatory): // The client ID associated with the application at the PO.

99

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.

101

102

- **usernameClaim **//(optional): // The user Identifier attribute requested by the RP and returned by the OP to identify the user who authenticates.

103

104

- **additionalScopes **//(optional) // : Additional scopes with an 'openid' scope separated by spaces.

105

)))

106

)))

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.

111

112

__Table describing the attributes of the Vavle element__

113

114

== Addition of the .war corresponding to the entry point of the Relying Party ==

115

116

Add the **digdash_oidc_endpoint.war** archive from the **apache-tomcat/webapps** folder to the folder

117

118

**<digdash_installation>/apache-tomcat/webapps**.

119

120

It is the entry point (endpoint) of the RP accessed by the PO.

121

122

== Addition of security constraints ==

123

124

Add the security constraints to the **web.xml** file located in the folder

125

126

**<digdash_installation>/apache-tomcat/conf** .

<web-app ... >

...

<security-role>

<role-name>CUSTOM</role-name>

133

</security-role>

134

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>

145

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>

...

</web-app>

__Extract from web.xml file__

157

158

== Server URL and domain for the Dashboard and Web Studio ==

159

160

It may be necessary, and **it is advisable** to specify on which server / domain the Dashboard will rely.

161

162

To do this, modify in the **web.xml** file in **<digdash_installation>/apache-tomcat/webapps/digdash_dashboard /WEB-INF.**

163

164

Do the same for the **web.xml** file in **<digdash_installation>/apache-tomcat/webapps/studio/WEB-INF**

165

166

To force the domain, change the value of the **FORCEDOMAIN** parameter to //true// .

167

Mention the domain name by changing the **DOMAIN** parameter .

168

169

To force the server address, change the value of the ** FORCEURLSERVER ** parameter to //true// . ** **Mention the server address by changing the **SERVERURL** parameter .

<web-app ... >

...

<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>

</init-param>

...

</servlet>

...

</web-app>

__Extract from web.xml file__

201

202

Values for parameters DOMAIN, FORCEDOAMIN, SERVERUEL, FORCESERVERURL are variable according to the installation.

|(((

* [[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

)))

210

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

214

215

(% style="background-color:transparent" %)**<user> / Application Data / Enterprise Server / dashboard_system.xml **

216

217

(((

218

For more information, you can refer to the DigDash documentation “guide_avance_systeme_fr.pdf”.

)))

)))

== Changing the value of the sharedPasswd parameter ==

223

224

Change the value of the //sharedPasswd// parameter (secret value below to change) in the **web.xml** file of Dashboard in the folders

225

226

**<digdash_installation>/apache-tomcat/webapps/digdash_dashboard/WEB-INF**

and

**<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).

<web-app ... >

...

<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>

</init-param>

...

</servlet>

...

</web-app>

__Extract from the server.xml file__

254

255

Value for parameter sharedPasswd is variable according to the installation.

256

257

== Modification of the authentication method ==

258

259

Modify the authentication method (LDAP is the default method) in the **web.xml** file located in the folder

260

261

**<digdash_installation>/apache-tomcat/webapps/ddenterpriseapi/WEB-INF** .

262

263

"External" means that safety is managed by the valve configured above.

<web-app ... >

...

...

</servlet>

...

<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>

</init-param>

...

</servlet>

...

</web-app>

__Extract from web.xml file__

288

289

= OpenID Provider configuration =

290

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.

292

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

294

295

https:~/~/<IP address>:<port>/digdash_oidc_endpoint/oidcendpoint

= Log level =

You can customize the log level for the authentication valve.

300

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 .

302

303

log4j.logger.org.bsworks = **ERROR** , stdout

304

305

log4j.logger.org.bsworks = **DEBUG** , stdout

306

307

= OpenID Connect authentication on the Enterprise Studio side =

308

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**

...

<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)

...

</application-desc>

</jnlp>

__Extract from the digdash.jnlp file__

333

334

__**Warning**__** **: the arguments noted (1), (2), (3), (4), (5) must not change order.

335

336

Argument (1): the address of the DigDash server; variable depending on your installation

337

338

Argument (2): the name of the DigDash domain; variable depending on your installation

339

340

Argument (5): The authentication method; External, mandatory

341

342

Argument (A): optional argument, sometimes necessary in the case of SSL, HTTPS connections.

343

344

== Connection to DigDash Enterprise Studio ==

345

346

Download and run the .jnlp by going to the DigDash home page in the Enterprise Studio section.

347

348

[[image:1592471261704-499.png||queryString="width=622&height=306" height="306" width="622"]]

349

350

An authentication window should appear with the IdP authentication target.

351

352

In this document, Google is the OP that we have chosen to illustrate our examples.

353

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

\\

356

357

__Capture: test pattern with Google OP authentication form__

358

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.

360

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

\\

363

364

__Capture: window of successful authentication__

365

366

The window will close automatically, then Enterprise Studio will start loading to launch.

367

368

= Lexicon =

369