SAMLv2 authentication

* Have the **<digdash_installation> / add-ons / valve_saml2 folder** containing all the files necessary for setting up the SAMLv2 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: acs sub-folder in a .war file to be placed in **<digdash_install> / apache-tomcat / webapps**

17

** The resources_samples folder: examples of XML files of IdP metadata and .properties file of security parameters to edit and place in the location of your choice.

18

** The sp_metadata folder: The SP DigDash metadata XML file.

19

20

* For the moment, DigDash only supports the disconnection initiated by the SP (SP-Initiated SLO).

21

22

* The following operations are to be performed on the **stopped** DigDash server .

23

24

* The user to be authenticated must exist both at the IdP and in the LDAP DigDash.

25

** **It is therefore advisable to have at least one user having the rights to add DigDash users in the LDAP DigDash before installing the SAMLv2 valve, this in order to avoid SSO authentication failures from the first connections due to absence of such user in LDAP.**

26

27

**Mutual exchange of SP and IdP metadata**

28

29

The two parties (Identity Provider and Service Provider) must first exchange their respective metadata in the form of XML files. This metadata will in particular make it possible to know their respective entry point and the details of secure exchanges.

30

31

= Configuration of the DigDash server =

32

33

== Copy of libraries ==

34

35

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

36

37

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

38

39

|saml2-valve.jar|slf4j-api-1.7.12.jar

40

|commons-codec-1.10.jar|log4j-1.2.15.jar

41

|commons-lang3-3.4.jar|slf4j-log4j12-1.7.7.jar

42

|commons-logging-1.2.jar|xmlsec-2.0.7.jar

43

|joda-time-2.9.4.jar|log4j.properties

44

45

__Libraries of the apache-tomcat / lib folder__

46

47

== Addition of the SAMLv2 authentication valve ==

48

49

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

50

51

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

52

53

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

...

<Valve className = "com.onelogin.saml2.SAML2SSOValve"

60

allowAddr = "localhost, 127.0.0. *, 0: 0: 0: 0: 0: 0 : 0: 1 "

61

idPMetadataPath = " C: \ idp_md.xml "

62

securitySettingsPath = " C: \ saml2.sec.properties "

63

uid = " email "

64

sharedPasswd = " sharedPassword " />

...

</Host>

...

< / Server>

__E__x extract from the server.xml file

72

73

Invariable value (className)

74

75

Variable value depending on the installation (allowAddr, idPMetadataPath, ...)

76

77

78

|Attribute|Description

79

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

80

|allowAddr|Server IP address.

81

|idPMetadataPath|The absolute path of the XML file with IdP metadata

82

|securitySettingsPath|The absolute path of the .properties file with security settings

83

|uid|One of the attributes returned by the IdP in the SAMLv2 response to identify the user who authenticates. If this attribute is not mentioned, the nameId of the SAMLv2 response is used to identify the user.

84

|sharedPasswd|The shared password and verified at authentication (see point II.5)

85

|//allowedCtxPath//|//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"

86

|//ldapForPaths//|//Optional// , these are regular expressions of URLs whose resources are authorized to pass the valve, thus going into LDAP authentication mode. Example: "http: ~/~/ localhost: 8080 /.*"

87

|//cookieTimeOut//|(((

88

//Optional// , this is the time (in seconds) after which the SSO cookie will expire. Worth 1800 seconds (30 minutes) by default.

89

Otherwise, the cookie will expire after the number of seconds mentioned.

90

91

Example: cookieTimeOut = "3600" (1 hour)

92

)))

93

|print_ //debug//|//Optional// , is false by default, otherwise add print_debug = "true" for more verbose traces.

94

95

__Table describing the attributes of the Valve element__

96

97

== Addition of the .war corresponding to the ACS of the Service Provider ==

98

99

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

100

101

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

102

103

It is the ACS entry point of the SP accessed by the IdP.

104

105

== Addition of security constraints ==

106

107

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

108

109

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

<web-app ... >

...

<security-role>

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

116

</security-role>

117

118

<security-constraint>

119

<display-name> CUSTOM Security Constraint </ display-name>

120

<web-resource-collection>

121

<web-resource-name> Protected Area </web-resource-name>

122

<url-pattern> / * </url-pattern>

123

</web-resource-collection>

124

<auth-constraint>

125

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

126

</auth-constraint>

127

</security-constraint>

128

129

<security-constraint>

130

<web-resource-collection>

131

<web-resource-name> Non-Protected Area</web-resource-name>

132

<url-pattern> / vjdbc </url-pattern>

133

</web-resource-collection>

134

</security-constraint>

...

</web-app>

__Extract from web.xml file__

140

141

== Server URL and domain for the Dashboard ==

142

143

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

144

145

To do this, modify in the **web.xml** file in

146

147

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

148

149

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

150

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

151

152

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

<web-app ... >

...

<servlet-name> dashServlet </servlet-name>

159

<servlet-class> com.digdash.server.DigdashServiceImpl </servlet-class>

160

...

161

<init-param>

162

<param-name> DOMAIN </param-name>

163

<param-value> ddenterpriseapi </param-value>

164

</init-param>

165

<init-param>

166

<param-name> FORCEDOMAIN </param-name>

167

<param-value> true </param-value>

168

</init-param>

169

<init-param>

170

<param-name> SERVERURL </ param-name>

171

<param-value> http: // localhost: 8080</param-value>

172

</init-param>

173

<init-param>

174

<param-name> FORCESERVERURL </param-name>

175

<param-value> true </param-value>

</init-param>

...

</servlet>

...

</web-app>

Extract from web.xml file

184

185

186

Variable value depending on the installation

187

188

189

|[[image:https://doc.digdash.com/xwiki/bin/download/Digdash_DEV/others_documents/config_auth_saml2/WebHome/config_auth_saml2_fr_test_html_829eaa34e529ef0c.png?width=72&height=72&rev=1.1||alt="config_auth_saml2_fr_test_html_829eaa34e529ef0c.png"]]

190

|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 usage. It will naturally be necessary to refer to the address of the external server if these two elements are placed on different servers.

191

192

|[[image:https://doc.digdash.com/xwiki/bin/download/Digdash_DEV/others_documents/config_auth_saml2/WebHome/config_auth_saml2_fr_test_html_829eaa34e529ef0c.png?width=72&height=72&rev=1.1||alt="config_auth_saml2_fr_test_html_829eaa34e529ef0c.png"]]

193

|(((

194

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

195

196

**<user> / Application Data / Enterprise Server / dashboard_system.xml**

197

198

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

199

)))

200

201

== Changing the value of the sharedPasswd parameter ==

202

203

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

204

205

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

206

207

The value must correspond to that mentioned in the //sharedPasswd// attribute in the valve of the file

208

209

**<digdash_installation> /apache-tomcat/conf/server.xml** (see part II.2).

<web-app ... >

...

<servlet-name> dashServlet </servlet-name>

216

<servlet-class> com.digdash.server.DigdashServiceImpl </servlet-class>

...

<init-param>

<param-name> sharedPasswd </param-name>

221

<param-value> secret </param-value>

</init-param>

...

</servlet>

...

</web-app>

Variable value depending on the installation

230

231

232

__Extract from the server.xml file__

233

234

== Modification of the authentication method ==

235

236

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

237

238

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

239

240

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

<web-app ... >

...

...

</servlet>

...

<display-name> DDEnterpriseAuthServlet </display-name>

252

<servlet-name > DDEnterpriseAuthServlet </servlet-name>

253

<servlet-class> com.digdash.server.DDEnterpriseAuthServlet </servlet-class>

254

255

<init-param>

256

<param-name> authMethod </param-name>

257

<param-value> External </param-value>

</init-param>

...

</servlet>

...

</web-app>

__Extract from web.xml file__

267

268

= Identity Provider Configuration =

269

270

The IdP will need to register DigDash as an SP in its SP list before DigDash can take advantage of Single Sign-On.

271

272

The IdP must in particular use the metadata file provided by the SP for its configuration. This mentions among other things the entry points of the SP DigDash (URL ACS).

273

274

== Service Provider metadata ==

275

276

The SP metadata will either be provided directly and physically (by email, by USB key, etc.) or by generation via the SP. Indeed, they will be accessible via the following URL once the valve is in place:

277

278

https: ~/~/ <DigDash server address>: <port> /? spmetadata = display

279

280

= Service Provider Configuration =

281

282

The SP must load the IdP metadata into its application.

283

284

== Identity Provider metadata ==

285

286

Place the file in XML format provided by the IdP corresponding to the IdP metadata in the directory of your choice.

287

288

**NB** : The absolute path of this file will be known and will be entered as the value of the idPMetadataPath attribute of the SAMLv2 valve.

289

290

= Configuration of security parameters =

291

292

Place the file in .properties format corresponding to the security parameters in the directory of your choice.

293

294

**NB1** : The absolute path of this file will be known and will be entered as the value of the securitySettingsPath attribute of the SAMLv2 valve.

295

296

The following table presents the different possible properties for setting security:

297

298

|Properties|Description

299

|(((

300

onelogin.saml2.sp.entityid

301

302

onelogin.saml2.sp.assertion_consumer_service.url

303

304

onelogin.saml2.sp.assertion_consumer_service.binding

305

306

onelogin.saml2.sp.single_logout_service.url

307

308

onelogin.saml2.sp.single_logout_service.binding

309

310

onelogin.saml2.sp.nameidformat

311

312

onelogin.saml2.sp.x509cert

313

314

onelogin.saml2.sp.privatekey

315

)))|(((

316

Properties relating to the Service Provider.

317

318

The default values of these properties are automatically loaded on the SP side.

319

320

If necessary, it is possible to override these properties by mentioning them in the properties file.

321

322

The more detailed description of these parameters as well as the values used can be directly consulted in the security file resources_samples \ saml2.sec.properties provided.

323

)))

324

|(% rowspan="2" %)onelogin.saml2.strict|Indicates whether the SP rejects all unencrypted or unsigned messages if the SP expects them to be.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.nameid_encrypted|Indicates if the nameID of the <samlp: logoutRequest> sent by the SP must be encrypted

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.authnrequest_signed|Indicates whether <samlp: AuthnRequest> messages sent by this SP are signed. Metadata indicates this information.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.logoutrequest_signed|Indicates whether the <samlp: logoutRequest> messages sent by this SP are signed.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.logoutresponse_signed|Indicates whether the <samlp: logoutResponse> messages sent by this SP are signed.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.want_messages_signed|Indicates if responses should be signed

355

|(((

356

true Message is required to be signed

357

358

false Message is not required to be signed

359

)))

360

|(% rowspan="2" %)onelogin.saml2.security.want_assertions_signed|Indicates the obligation of the <samlp: Response>, <samlp: LogoutRequest> and <samlp: LogoutResponse> messages received by this SP to be signed.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.sign_metadata|Indicates the obligation of the metadata of this SP to be signed.

367

|(((

368

true requires signature of metadata

false default

)))

|(% rowspan="2" %)onelogin.saml2.security.want_assertions_encrypted|Indicates the obligation of assertions received by this SP to be encrypted.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.want_nameid_encrypted|Indicates the obligation of the nameID received by the SP to be encrypted.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.requested_authncontext|Authentication context

385

|(((

386

Empty if you don't want any context to be sent in the AuthnRequest request

387

388

Multiple values separated by commas otherwise.

389

)))

390

|(% rowspan="2" %)onelogin.saml2.security.onelogin.saml2.security.requested_authncontextcomparison|Enables authentication context comparison

391

|'exact' by default

392

|(% rowspan="2" %)onelogin.saml2.security.want_xml_validation|Indicates whether the SP validates all XML responses received. (If true, validation is only effective if this property and the 'onelogin.saml2.strict' property is also true.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.signature_algorithm|Hash algorithm used for signature.

399

|(((

400

http:~/~/www.w3.org/2000/09/xmldsig#rsa-sha1

401

402

http:~/~/www.w3.org/2000/09/xmldsig#dsa-sha1

403

404

http:~/~/www.w3.org/2001/04/xmldsig-more#rsa-sha256

405

406

http:~/~/www.w3.org/2001/04/xmldsig-more#rsa-sha384

407

408

http:~/~/www.w3.org/2001/04/xmldsig-more#rsa-sha512

409

)))

410

411

__Table describing possible security settings__

412

413

|[[image:https://doc.digdash.com/xwiki/bin/download/Digdash_DEV/others_documents/config_auth_saml2/WebHome/config_auth_saml2_fr_test_html_cfd0582386f81fc1.png?width=58&height=58&rev=1.1||alt="config_auth_saml2_fr_test_html_cfd0582386f81fc1.png"]]

414

|The shaded fields are fields offered by the onelogin library but which are not yet implemented for the SAMLv2 valve from DigDash, therefore not taken into account.

415

416

= VI. **Configuring the Java environment** =

417

418

The Java Cryptography Extension (JCE) is required. You can download the jce-6, jce-7 or jce-8 version, and unzip it in the folder

419

420

**$ {java.home} / jre / lib / security /**

421

422

|**Versions**|**Download links**

423

|jce-6|__[[http:~~/~~/www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html>>url:http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html]]__

424

|jce-7|__[[http:~~/~~/www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html>>url:http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html]]__

425

|jce-8|__[[http:~~/~~/www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html>>url:http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html]]__

= Log level =

You can customize the log level for the authentication valve.

430

431

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 .

432

433

log4j.logger.com.onelogin.saml2 = **ERROR** , stdout

434

435

log4j.logger.com.onelogin.saml2 = **DEBUG** , stdout

436

437

= SAML2 authentication on the Enterprise Studio side =

438

439

To authenticate with SAMLv2 on the Enterprise Studio side, please ensure that you have performed the following actions:

440

441

== Server and domain definitions in the .jnlp file ==

442

443

You can, like the Dashboard, define the server and the domain on which DigDash will rely.

444

445

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

451

452

<argument> https: // localhost: 8443 </argument> (1)

453

<argument> ddenterpriseapi </argument> (2 )

454

<argument><%=lang%> </argument> (3)

455

<argument><%=dashboard%> </argument> (4)

456

<argument> -AuthMode = External </argument> (5)

457

<argument> -SSLNoPathCheck </argument> (A)

...

</application-desc>

</jnlp>

Extract from the digdash.jnlp file

464

465

466

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

467

468

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

469

470

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

471

472

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

473

474

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

475

476

== Connection to DigDash Enterprise Studio ==

477

478

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

479

480

[[image:https://doc.digdash.com/xwiki/bin/download/Digdash_DEV/others_documents/config_auth_saml2/WebHome/config_auth_saml2_fr_test_html_27c2ab581e0d9d7e.png?width=554&height=274&rev=1.1||alt="config_auth_saml2_fr_test_html_27c2ab581e0d9d7e.png"]]

481

\\

482

483

An authentication window should appear with the IdP authentication target.

484

485

In this document, Salesforce is the IdP we have chosen to illustrate our examples.

486

487

[[image:https://doc.digdash.com/xwiki/bin/download/Digdash_DEV/others_documents/config_auth_saml2/WebHome/config_auth_saml2_fr_test_html_dff5c9e389ba1c1d.png?width=666&height=409&rev=1.1||alt="config_auth_saml2_fr_test_html_dff5c9e389ba1c1d.png"]]

488

\\

489

490

__Capture: target with Salesforce IdP authentication form__

491

492

The user must enter his login data and if he has been authenticated with the IdP 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 authentication.

493

494

[[image:https://doc.digdash.com/xwiki/bin/download/Digdash_DEV/others_documents/config_auth_saml2/WebHome/config_auth_saml2_fr_test_html_6230a5f637fd4c54.png?width=612&height=376&rev=1.1||alt="config_auth_saml2_fr_test_html_6230a5f637fd4c54.png"]]

495

\\

496

497

__Capture: window of successful authentication__

498

499

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

500

501

= Lexicon =

502