SAMLv2 authentication

* Have the **<Install DD>/add-ons/valve_saml2** folder containing all the files needed to set up the SAMLv2 authentication valve in the Tomcat server. The placement of these files is described in this document.

21

** The apache-tomcat folder: transposed to **/etc/tomcat9/** under Linux **and C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf **under Windows

22

*** The lib sub-folder: libraries and log configuration file to be placed in:

23

**** Under Linux: **/usr/share/tomcat9/lib/**

24

**** Under Windows : **C:\Program Files\Apache Software Foundation\Tomcat 9.0\lib**

25

*** The sub-folder webapps : ACS in a .war to be placed in :

26

**** Under Linux: **/home/digdash/webapps/default**

27

**** Under Windows: **E:/digdash/webapps/default**

28

** The resources_samples folder: examples of IdP metadata XML files and security parameter .properties files to be edited and placed in the desired location.

29

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

30

31

* For the moment, only SP-initiated disconnection (SP-Initiated SLO) is supported.

32

* The following operations must be carried out with the DigDash server **stopped**.

33

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

34

* (((

35

If a reverse proxy is used, check header transmission: the reverse proxy used must allow X-Forwarded-Proto and X-Forwarded-Host headers to communicate.

36

)))

37

38

(% class="box warningmessage" %)

39

(((

40

It is advisable to have at least one user with the right to add users to the LDAP before installing the SAMLv2 valve, in order to avoid SSO authentication failures on the first connections due to the absence of such a user in the LDAP.

41

)))

42

43

**Mutual exchange of SP and IdP metadata**

44

45

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

46

47

= Configuring the DigDash server =

48

49

== Copying libraries ==

50

51

Copy the libraries and the log configuration file from the **<install DD>/add-ons/valve_saml2/apache-tomcat/lib** folder to the :

(% class="box" %)

(((

* under Linux: **/usr/share/tomcat9/lib/**

56

* under Windows : **C:\Program Files\Apache Software Foundation\Tomcat 9.0\lib**

)))

Files to copy :

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

62

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

63

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

64

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

65

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

66

67

== Adding the SAMLv2 authentication valve ==

68

69

Activate the SAMLv2 authentication valve in the **server.xml** file located in the :

(% class="box" %)

(((

* under Linux: **/etc/tomcat9/**

74

* under Windows : **C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf**

75

)))

76

77

To do this, look for the **<Host ...>** element in the file, uncomment or add the **<Valve ...>** element below:

(((

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

82

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

83

fallbackAuth="LDAP"

84

idPMetadataPath="C:\idp_md.xml"

85

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

86

uid="email"

87

sharedPasswd="sharedPassword" ></Valve>

88

89

90

The value of the //className //attribute is invariant.

91

92

The values of the other attributes (allowAddr, idPMetadataPath, ...) are variable depending on the installation.

93

)))

94

95

|(% style="width:247px" %)**Attribute**|(% style="width:1173px" %)**Description**

96

|(% style="width:247px" %)className|(% style="width:1173px" %)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.

97

|(% style="width:247px" %)allowAddr|(% style="width:1173px" %)IP address of the server.

98

|(% style="width:247px" %)fallbackAuth|(% style="width:1173px" %)The fallback authentication method

99

|(% style="width:247px" %)idPMetadataPath|(% style="width:1173px" %)The absolute path of the XML file containing the IdP's metadata

100

|(% style="width:247px" %)securitySettingsPath|(% style="width:1173px" %)The absolute path to the .properties file with the security settings

101

|(% style="width:247px" %)uid|(% style="width:1173px" %)One of the attributes returned by the IdP in the SAMLv2 response to identify the authenticating user. If this attribute is not mentioned, the nameId from the SAMLv2 response is used to identify the user.

102

|(% style="width:247px" %)sharedPasswd|(% style="width:1173px" %)The password shared and verified at authentication. A hash in SSHA512 format can be used to avoid writing the password in the plaintext file (a tool such as pwdhash can be used under Linux to generate this hash).

103

|(% style="width:247px" %)//ldapForPaths//|(% style="width:1173px" %)//Optional//, these are regular expressions for URLs whose resources are authorised to pass the valve, thereby switching to LDAP authentication mode. Example: "http:~/~/localhost:8080/.*"

104

|(% style="width:247px" %)//excludedPaths//|(% style="width:1173px" %)//Optional,// these are the regular expressions of the paths whose resources are authorised to pass the valve, thus switching to LDAP authentication mode. Example: "/.*"

105

|(% style="width:247px" %)//cookieTimeOut//|(% style="width:1173px" %)(((

106

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

107

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

108

109

A negative value means that the cookie will expire when the browser is closed.

110

A value of 0 means that the cookie will be deleted directly (not recommended).

111

112

Example: cookieTimeOut="3600" (1 hour)

113

)))

114

|(% style="width:247px" %)//print_debug//|(% style="width:1173px" %)//Optional//, set to false by default, otherwise add print_debug="true" for more verbose traces.

115

116

== Add the .war file corresponding to the Service Provider ACS ==

117

118

Add the **ddacs.war** archive from the **<install DD>/add-ons/valve_saml2/apache-tomcat/webapps** folder to the :

(% class="box" %)

(((

* under Linux: **/home/digdash/webapps/default**

123

* under Windows: **E:/digdash/webapps/default**

124

)))

125

126

(% class="box infomessage" %)

127

(((

128

This is the ACS entry point for the SP accessed by the IdP.

129

)))

130

131

== Adding security constraints ==

132

133

Uncomment or add the security constraints to the **web.xml** file located in the :

(% class="box" %)

(((

* under Linux: **/etc/tomcat9/**

138

* under Windows: **C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf**

)))

<web-app ...>

...

<security-role>

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

146

</security-role>

147

148

<security-constraint>

149

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

150

151

<web-resource-collection>

152

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

153

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

154

</web-resource-collection>

155

156

<auth-constraint>

157

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

158

</auth-constraint>

159

</security-constraint>

160

161

<security-constraint>

162

<web-resource-collection>

163

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

164

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

165

</web-resource-collection>

166

</security-constraint>

...

</web-app>

= Application configuration =

173

174

To do this, modify the **digdash.properties** file in **<install DD> **or** /etc/digdash** (under Linux) or in the folder you have configured.

175

176

177

== Server configuration (ddenterprise.war) ==

178

179

In the **digdash.properties** file:

180

181

In the //ddenterpriseapi.war// box, find and uncomment the following lines with the values shown:

182

183

184

ddenterpriseapi.authMethod=External

== Dashboard configuration (digdash_dashboard.war) ==

189

190

In the **digdash.properties** file :

191

192

In the //digdash_dashbord.war// box, find and uncomment the following lines with the values shown:

193

194

195

digdash_dashboard.SERVERURL=http://localhost:8080

196

digdash_dashboard.DOMAIN=ddenterpriseapi

197

digdash_dashboard.FORCEDOMAIN=true

198

digdash_dashboard.FORCESERVERURL=true

199

digdash_dashboard.sharedPasswd=<la valeur de l'attribut sharedPasswd dans l'élément Valve>

200

201

202

(% class="box infomessage" %)

203

(((

204

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.

)))

== Studio configuration (studio.war) ==

209

210

In the **digdash.properties** file :

211

212

In the //studio.war// box, find and uncomment the following lines with the values shown:

213

214

215

studio.SERVERURL=http://localhost:8080

216

studio.DOMAIN=ddenterpriseapi

217

studio.FORCEDOMAIN=true

218

studio.FORCESERVERURL=true

219

studio.PUBLICSERVERURL=<votre adresse URL publique>

220

studio.sharedPasswd=<la valeur de l'attribut sharedPasswd dans l'élément Valve>

221

222

223

(% class="box infomessage" %)

224

(((

225

The parameter //studio.PUBLICSERVERURL//is optional when installing an SSO.

226

227

The example value for this parameter 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, reference will have to be made to the address of the external server if these two elements are placed on different servers.

228

)))

229

230

== Configuring the Identity Provider ==

231

232

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

233

The IdP will need to use the metadata file provided by the SP for its configuration. Among other things, this file mentions the DigDash SP entry points (ACS URLs).

234

235

== Service Provider metadata ==

236

237

The SP metadata will either be supplied directly and physically (by email, USB key, etc.) or by generation via the SP. It will be accessible via the following URL once the valve has been set up:

238

239

(% class="box infomessage" %)

240

(((

241

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

242

)))

243

244

= Configuring the Service Provider =

245

246

The SP must load the IdP metadata into its application.

247

248

== Identity Provider metadata ==

249

250

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

251

252

(% class="box infomessage" %)

253

(((

254

The absolute path of this file must be known and must be entered as the value of the //idPMetadataPath //attribute of the Valve element in Tomcat.

255

)))

256

257

If the .xml metadata file is not read by the IdP, the following parameters must be set as indicated below:

258

259

* entity id: https:~/~/[serveur_url]/?spmetadata=display

260

* reply: https:~/~/[serveur_url]/ddacs/acs

261

262

= Configuring security parameters =

263

264

Place the saml2.sec.properties file in the **<Install DD>/add-ons/valve_saml2/resources_samples** folder corresponding to the security parameters in the directory of your choice.

265

266

(% class="box infomessage" %)

267

(((

268

The absolute path of this file must be known and must be entered as the value of the //securitySettingsPath //attribute of the Valve element in Tomcat.

269

)))

270

271

The following tables show the various properties for setting security parameters:

272

273

== General properties ==

274

275

|(% style="width:279px" %)**General property**|(% style="width:808px" %)**Description**|(% style="width:332px" %)**Possible values**

276

|(% style="width:279px" %)onelogin.saml2.strict|(% style="width:808px" %)If true, the SP is in strict mode and will reject all unencrypted or unsigned messages if the SP expects them to be.|(% style="width:332px" %)true,false

277

|(% style="width:279px" %)onelogin.saml2.debug|(% style="width:808px" %)If true, debug mode will be enabled.|(% style="width:332px" %)true,false

278

279

== Service Provider properties ==

280

281

(% class="box infomessage" %)

282

(((

283

The default values for these properties are automatically loaded. You can uncomment certain properties as required to make values more explicit.

284

)))

285

286

|(% style="width:364px" %)**Service Provider properties**|(% style="width:592px" %)**Description**|(% style="width:507px" %)**Possible values**

287

|(% style="width:364px" %)onelogin.saml2.sp.entityid|(% style="width:592px" %)the identifier of the Service Provider entity|?spmetadata=display

288

|(% style="width:364px" %)onelogin.saml2.sp.assertion_consumer_service.url|(% style="width:592px" %)SP entry point. This is the URL to which the IdP's SAML <Response> will be returned.|ddacs/acs

289

|(% style="width:364px" %)onelogin.saml2.sp.assertion_consumer_service.binding|(% style="width:592px" %)(((

290

SAML protocol binding used when returning the <Response> message. Onelogin supports HTTP-POST binding only for this endpoint.

291

)))|urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

292

|(% style="width:364px" %)onelogin.saml2.sp.single_logout_service.url|(% style="width:592px" %)Specifies where and how the <Logout Response> message should be returned to the requester, in this case the SP.|ddacs/slo

293

|(% style="width:364px" %)onelogin.saml2.sp.single_logout_service.binding|(% style="width:592px" %)SAML protocol binding used when returning the <LogoutResponse> or sending the <LogoutRequest> message. Onelogin supports HTTP-Redirect binding only for this endpoint.|urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

294

|(% style="width:364px" %)onelogin.saml2.sp.nameidformat|(% style="width:592px" %)Specifies constraints on the NameID to be used to represent the user to be authenticated.|urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

295

|(% style="width:364px" %)onelogin.saml2.sp.x509cert|(% style="width:592px" %)The Service Provider's public key (or certificate).|See documentation [[SAMLv2 Authentication - Configuration>>doc:.config_auth_saml2_sec.WebHome]]

296

|(% style="width:364px" %)onelogin.saml2.sp.privatekey|(% style="width:592px" %)The Service Provider's private key.|See documentation [[SAMLv2 Authentication - Configuration>>doc:.config_auth_saml2_sec.WebHome]]

297

298

== Security properties ==

299

300

|(% style="width:411px" %)**Security properties**|(% style="width:690px" %)**Description**|(% style="width:319px" %)**Possible values**

301

|(% rowspan="1" style="width:411px" %)onelogin.saml2.security.nameid_encrypted|(% style="width:690px" %)Specifies whether the nameID of the <samlp:logoutRequest> sent by the SP should be encrypted.|(% style="width:319px" %)true,false

302

|(% rowspan="1" style="width:411px" %)onelogin.saml2.security.authnrequest_signed|(% style="width:690px" %)Indicates whether <samlp:AuthnRequest> messages sent by this SP are signed. The metadata indicates this information.|(% style="width:319px" %)true,false

303

|(% rowspan="1" style="width:411px" %)onelogin.saml2.security.logoutrequest_signed|(% style="width:690px" %)Indicates whether <samlp:logoutRequest> messages sent by this SP are signed.|(% style="width:319px" %)true,false

304

|(% rowspan="1" style="width:411px" %)onelogin.saml2.security.logoutresponse_signed|(% style="width:690px" %)Indicates whether <samlp:logoutResponse> messages sent by this SP are signed.|(% style="width:319px" %)true,false

305

|(% rowspan="1" style="width:411px" %)onelogin.saml2.security.want_messages_signed|(% style="width:690px" %)Indicates whether responses should be signed.|(% style="width:319px" %)true,false

306

|(% rowspan="1" style="width:411px" %)onelogin.saml2.security.want_assertions_signed|(% style="width:690px" %)Indicates whether <samlp:Response>, <samlp:LogoutRequest> and <samlp:LogoutResponse> messages received by this SP must be signed.|(% style="width:319px" %)true,false

307

|(% rowspan="1" style="width:411px" %)onelogin.saml2.security.sign_metadata|(% style="width:690px" %)Indicates the requirement for this SP's metadata to be signed.|(% style="width:319px" %)true,false

308

|(% rowspan="1" style="width:411px" %)onelogin.saml2.security.want_assertions_encrypted|(% style="width:690px" %)Indicates that the assertions received by this SP must be encrypted.|(% style="width:319px" %)true,false

309

|(% rowspan="1" style="width:411px" %)onelogin.saml2.security.want_nameid_encrypted|(% style="width:690px" %)Indicates that the nameID received by the SP must be encrypted.|(% style="width:319px" %)true,false

310

|(% rowspan="1" style="width:411px" %)onelogin.saml2.security.requested_authncontext|(% style="width:690px" %)Authentication context.|(% style="width:319px" %)urn:oasis:names:tc:SAML:2.0:ac:classes:Password

311

or empty string if you do not want any context to be sent in the request.

312

Several possible values, separated by commas.

313

|(% rowspan="1" style="width:411px" %)onelogin.saml2.security.requested_authncontextcomparison|(% style="width:690px" %)Enable authentication context comparison|(% style="width:319px" %)exact

314

|(% rowspan="1" style="width:411px" %)onelogin.saml2.security.want_xml_validation|(% style="width:690px" %)Indicates whether the SP validates all XML responses received (if true, validation is only effective if this property and the 'onelogin.saml2.strict' property are also true).|(% style="width:319px" %)true,false

315

|(% rowspan="1" style="width:411px" %)onelogin.saml2.security.signature_algorithm|(% style="width:690px" %)Hash algorithm used for the signature.|(% style="width:319px" %)[[http:~~/~~/www.w3.org/2000/09/xmldsig#rsa-sha1

316

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

317

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

318

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

319

http:~~/~~/www.w3.org/2001/04/xmldsig-more#rsa-sha512>>http://www.w3.org/2000/09/xmldsig#rsa-sha1http://www.w3.org/2000/09/xmldsig#dsa-sha1http://www.w3.org/2001/04/xmldsig-more#rsa-sha256http://www.w3.org/2001/04/xmldsig-more#rsa-sha384http://www.w3.org/2001/04/xmldsig-more#rsa-sha512]]

320

321

(% class="wikigeneratedid" id="HConfigurationdel2019environnementJava" %)

322

(% style="color:inherit; font-family:inherit; font-size:max(23px, min(29px, 12.3333px + 1.38889vw))" %)Configuring the SAML 2 valve logs

323

324

In the server.xml file (located in the /etc/tomcat9/ folder under Linux or C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf under Windows), inside the **host** tag, add the following valve to obtain logs:

325

326

327

<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"

328

prefix="localhost_access_log_test_header" suffix=".log"

329

pattern="%h %l %u %t "%r" %s %b - X-Forwarded-Proto: %{X-Forwarded-Proto}i - X-Forwarded-For: %{X-Forwarded-For}i - X-Forwarded- Host : %{X-Forwarded-Host }i" ></Valve>

330

331

332

In the example above, the log files will start with "localhost_access_log_test_header". The prefix can be modified as required.

333

The logs will be located in the Tomcat folder.

== Log level ==

You can customise the log level for the authentication valve.

338

339

By default, only errors are logged. However, if you want to have more details about the course of actions and exchanges between the various entities, you can assign the value 'DEBUG' instead of 'ERROR' in the log4j.properties file which has been imported into the Tomcat lib folder.

340

341

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

342

becomes

343

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

344

345

= SAMLv2 and LDAP DigDash coexistence (optional) =

346

347

It is possible to use direct authentication via the DigDash LDAP directory while the SAMLv2 method is in place on your DigDash server.

348

349

== Prior configuration ==

350

351

In the **digdash.properties** file :

352

353

In the //studio.war// box, find and uncomment the following lines with the values shown:

354

355

356

studio.allowLoginForm=true

357

358

359

In the //digdash_dashboard.war// box, find and uncomment the following lines with the values shown:

360

361

362

digdash_dashboard.allowLoginForm=true

== Enabling DigDash LDAP mode ==

367

368

To activate the DigDash LDAP authentication mode, simply add the **loginForm **parameter to the URL with the value (% style="color:#27ae60" %)**true**(%%).

369

370

So, if you need to authenticate to the dashboard directly using your DigDash LDAP credentials when SAMLv2 is already installed, the URL to use will be in the form :

(% class="box" %)

(((

https:~/~/<host>:<port>/digdash_dashboard/index.html**?(% style="color:#27ae60" %)loginForm=true(%%)**

375

)))

376

377

(% class="box warningmessage" %)

378

(((

379

(% style="color:#e67e22" %)**Please note **(%%): in general, the loginForm parameter and its value should be specified on each domain independently of the others (ddenterpriseapi for the server, digdash_dashboard for the dashboard, studio for the web studio) in order to authenticate via LDAP.

380

Activating the loginForm parameter on the dashboard (digdash_dashboard domain) will not automatically activate it on the web studio (studio domain), for example.

381

)))

382

383

== Re-enabling SAMLv2 mode ==

384

385

To deactivate the DigDash LDAP mode and return to a state where SAMLv2 SSO authentication is used, simply set the **loginForm **parameter to (% style="color:#c0392b" %)**false**(%%).

386

If you need to authenticate to the dashboard via SAMLv2 when direct authentication via DigDash LDAP was previously used, the URL to use will be in the form :

(% class="box" %)

(((

https:~/~/<host>:<port>/digdash_dashboard/index.html**?(% style="color:#c0392b" %)loginForm=false(%%)**

391

)))

392

393

The previous warning note should also be taken into account in this case.\\

394

395

== Using a reverse proxy ==

396

397

When using a reverse proxy, the remote IP valve must be adapted.

398

399

Open the **server.xml **file located in the :

(% class="box" %)

(((

* under Linux: **/etc/tomcat9/**

404

* under Windows: **C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf**

405

)))

406

407

In this file, the remote IP valve is entered as follows:

408

409

{{{<Valve className="org.apache.catalina.valves.RemoteIpValve" internalProxies="127\.0\.[0-1]\.1" remoteIpHeader="x-forwarded-for" requestAttributesEnabled="true" protocolHeader="x-forwarded-proto" protocolHeaderHttpsValue="https"/>}}}

410

411

Replace the value of the **internalProxies** property with the value of the reverse proxy IP as shown below.

412

413

{{{<Valve className="org.apache.catalina.valves.RemoteIpValve" internalProxies="<IP OF REVERSE PROXY>" remoteIpHeader="x-forwarded-for" requestAttributesEnabled="true" protocolHeader="x-forwarded-proto" protocolHeaderHttpsValue="https"/>}}}

= Glossary =

In this document we will refer to :

418

419

* **ACS:** Assertion Consumer Service

420

* **IdP**: Identity Provider

421