Authentification SAMLv2

1

Mise en place d’une valve d’authentification SAMLv2 pour DigDash

2

----

= Prérequis =

* Les acronymes utilisés par la suite sont référencés dans le lexique, à la fin de ce document.

10

* Avoir configuré le serveur avec un connecteur SSL/TLS (HTTPS) (cette méthode d'authentification requiert des échanges sécurisés).

11

* Disposer du dossier **<DD Install>/add-ons/valve_saml2** contenant tous les fichiers nécessaires à la mise en place de la valve d’authentification SAMLv2 dans le serveur Tomcat. Le placement de ces fichiers est décrit dans ce document.

12

** Le dossier apache-tomcat : transposé à **<DD Install>/apache-tomcat**

13

*** Le sous-dossier lib : librairies et fichier de configuration des logs à placer dans **<DD Install>/apache-tomcat/lib**

14

*** Le sous-dossier webapps : acs dans un .war à placer dans **<DD Install>/apache-tomcat/webapps**

15

** Le dossier resources_samples : exemples de fichiers XML des métadonnées de l’IdP et de fichier .properties des paramètres de sécurité à éditer et placer à l’emplacement voulu.

16

** Le dossier sp_metadata : Le fichier XML de métadonnées du SP DigDash.

17

18

* Pour le moment, seule la déconnexion initiée par le SP (SP-Initiated SLO) est prise en charge.

19

20

* Les manipulations suivantes sont à réaliser le serveur DigDash **stoppé**.

21

22

* L’utilisateur à authentifier doit exister à la fois chez l’IdP et dans le LDAP.

23

24

(% class="box warningmessage" %)

25

(((

26

Il est conseillé d’avoir au moins un utilisateur ayant les droits d’ajout d’utilisateurs dans le LDAP avant d’installer la valve SAMLv2, ceci afin d’éviter les échecs d’authentification SSO dès les premières connexions pour cause d’absence de tel utilisateur dans le LDAP.

27

)))

28

29

**Échanges mutuels des métadonnées du SP et de l’IdP**

30

31

Les deux parties (Identity Provider et Service Provider) devront au préalable s’échanger mutuellement leurs métadonnées respectives sous la forme de fichiers XML . Ces métadonnées permettront notamment de connaître leur point d’entrée respectif et les détails des échanges sécurisés.

32

33

= Configuration du serveur DigDash =

34

35

== Copie des librairies ==

36

37

Ajoutez les librairies ainsi que le fichier de configuration des logs du dossier **<DD Install>/apache-tomcat/lib** dans le dossier

38

39

**<DD Install>/apache/lib**:

40

41

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

42

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

43

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

44

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

45

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

46

47

//__Librairies du dossier apache-tomcat/lib__//

48

49

== Ajout de la valve d’authentification SAMLv2 ==

50

51

Ajoutez la valve d’authentification SAMLv2 dans le fichier **server.xml** situé dans le dossier

52

53

**<DD Install>/apache-tomcat/conf**

54

55

Pour cela, ajoutez l’élément Valve suivant dans l’élément **Host**.

(((

...

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

64

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

65

idPMetadataPath="C:\idp_md.xml"

66

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

67

uid="email"

68

sharedPasswd="sharedPassword"

></Valve>

...

</Host>

...

</Server>

//__Extrait du fichier server.xml__//

77

78

Valeur invariable (className)

79

80

Valeur variable selon l’installation (allowAddr, idPMetadataPath, ...)

81

)))

82

83

|Attribut|Description

84

|className|Nom de la classe Java, implémentant l'interface org.apache.catalina.Valve, à utiliser comme Valve ici. Cet attribut est obligatoire, car il permet de sélectionner la Valve à utiliser. Il en existe en effet plusieurs implémentations fournies par Tomcat.

85

|allowAddr|Adresse IP du serveur.

86

|idPMetadataPath|Le chemin absolu du fichier XML avec les métadonnées de l’IdP

87

|securitySettingsPath|Le chemin absolu du fichier .properties avec les paramètres de sécurité

88

|uid|Un des attributs renvoyés par l’IdP dans la réponse SAMLv2 pour identifier l’utilisateur qui s’authentifie. Si cet attribut n’est pas mentionné, le nameId de la réponse SAMLv2 est utilisé pour identifier l’utilisateur.

89

|sharedPasswd|Le mot de passe partagé et vérifié à l’authentification (voir point II.5)

90

|//allowedCtxPath//|//Facultatif//, vaut "/adminconsole" par défaut ; il s’agit du chemin du contexte dont les ressources sont autorisées à passer la valve, utile lorsque l’adminconsole est nommé autrement. Exemple : allowedCtxPath="/customadminconsole"

91

|//ldapForPaths//|//Facultatif//, il s’agit des expressions régulières des URLs dont les ressources sont autorisées à passer la valve, passant ainsi en mode d’authentification LDAP. Exemple : "http:~/~/localhost:8080/.*"

92

|//cookieTimeOut//|(((

93

//Facultatif//, il s’agit du temps (en secondes) au bout duquel le cookie SSO expirera. Vaut 1800 secondes (30 minutes) par défaut .

94

Sinon, le cookie expirera après le nombre de secondes mentionné.

95

96

Exemple : cookieTimeOut="3600" (1 heure)

97

)))

98

|print_//debug//|//Facultatif//, vaut false par défaut, sinon, ajouter print_debug="true" pour des traces plus verbeuses.

99

100

//__Tableau décrivant les attributs de l’élément Valve__//

101

102

== Ajout du .war correspondant à l’ACS du Service Provider ==

103

104

Ajoutez l’archive **ddacs.war** du dossier **apache-tomcat/webapps** dans le dossier

105

106

**<DD Install>/apache-tomcat/webapps**.

107

108

(% class="box infomessage" %)

109

(((

110

Il s’agit du point d’entrée ACS du SP accédé par l’IdP.

111

)))

112

113

== Ajout des contraintes de sécurité ==

114

115

Ajoutez les contraintes de sécurité au fichier **web.xml** situé dans le dossier

116

117

**<DD Install>/apache-tomcat/conf**.

<web-app ...>

...

<security-role>

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

124

</security-role>

125

126

<security-constraint>

127

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

128

129

<web-resource-collection>

130

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

131

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

132

</web-resource-collection>

133

134

<auth-constraint>

135

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

136

</auth-constraint>

137

</security-constraint>

138

139

<security-constraint>

140

<web-resource-collection>

141

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

142

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

143

</web-resource-collection>

144

</security-constraint>

...

</web-app>

//__Extrait du fichier web.xml__//

150

151

== URL du serveur et domaine pour le Dashboard ==

152

153

(% class="box warningmessage" %)

154

(((

155

**Il est fortement conseillé** de préciser sur quel serveur/domaine le Dashboard va s’appuyer.

156

)))

157

158

Pour cela, modifiez dans le fichier **web.xml** dans

159

160

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

161

162

Pour forcer le domaine, changez la valeur du paramètre **FORCEDOMAIN** à //true//.

163

Mentionnez le nom du domaine en changeant le paramètre **DOMAIN**.

164

165

Pour forcer l’adresse du serveur, changer la valeur du paramètre** FORCESERVERURL **à //true//.** **Mentionnez l’adresse du serveur en changeant le paramètre **SERVERURL**.

<web-app ...>

...

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

172

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

173

...

174

<init-param>

175

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

176

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

</init-param>

<init-param>

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

181

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

</init-param>

<init-param>

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

186

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

</init-param>

<init-param>

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

191

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

</init-param>

...

</servlet>

...

</web-app>

(((

__//Extrait du fichier web.xml//__

)))

(((

(% class="box infomessage" %)

205

(((

206

Valeur variable selon l’installation

)))

)))

La valeur d’exemple pour le paramètre SERVERURL fera quasiment toujours référence à localhost, lorsque le tableau de bord et le serveur sont placés dans le même serveur Tomcat, ce qui représente quasiment 99 % des usages. Il faudra naturellement faire référence à l’adresse du serveur externe si ces deux éléments sont placés sur des serveurs différents.

211

212

Ce paramètre est éditable via le fichier web.xml comme indiqué ci-dessus. Ce fichier est propre à chaque installation. Il vous est possible de renseigner ce paramètre de manière plus globale dans le fichier.

213

214

215

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

216

217

(% class="box infomessage" %)

218

(((

219

Pour en savoir plus, vous pouvez vous référer à la documentation DigDash « [[Guide avancé système>>doc:Digdash.deployment.configuration.advanced_system_guide.WebHome]] »

220

)))

221

222

== Changement de la valeur du paramètre sharedPasswd ==

223

224

Changez la valeur du paramètre //sharedPasswd// (valeur secret ci-dessous à changer) dans le fichier **web.xml** de Dashboard dans le dossier

225

226

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

227

228

La valeur doit correspondre à celle mentionnée dans l’attribut //sharedPasswd// dans la valve du fichier

229

230

**<DD Install>/apache-tomcat/conf/server.xml** (voir partie II.2).

<web-app ...>

...

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

237

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

...

<init-param>

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

242

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

</init-param>

...

</servlet>

...

</web-app>

(((

//__Extrait du fichier server.xml__//

252

)))

253

254

== Modification de la méthode d'authentification ==

255

256

Modifiez la méthode d'authentification (LDAP est la méthode par défaut) dans le fichier **web.xml** situé dans le dossier :

257

258

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

(((

<web-app ...>

...

...

</servlet>

...

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

271

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

272

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

273

274

<init-param>

275

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

276

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

</init-param>

...

</servlet>

...

</web-app>

//__Extrait du fichier web.xml__//

285

286

(% class="box infomessage" %)

287

(((

288

"External" signifie que la sécurité est gérée par la valve configurée ci-dessus.

)))

)))

= Configuration de l’Identity Provider =

293

294

L’IdP devra enregistrer DigDash en tant que SP dans sa liste de SP pour que DigDash puisse tirer profit de l’Authentification unique.

295

296

L’IdP devra notamment se servir du fichier métadonnées fournit par le SP pour sa configuration. Celui-ci mentionne entre autres choses les points d’entrées du SP DigDash (URL ACS).

297

298

== Métadonnées du Service Provider ==

299

300

Les métadonnées du SP seront soit fournis directement et physiquement (par email, par clé USB, etc.) soit par génération via le SP. En effet, elles seront accessibles via l’URL suivante une fois la valve mise en place :

301

302

(% class="box infomessage" %)

303

(((

304

https:~/~/<adresse du serveur DigDash>:<port>/?spmetadata=display

305

)))

306

307

= Configuration du Service Provider =

308

309

Le SP devra charger dans son application les métadonnées de l’IdP.

310

311

== Métadonnées de l’Identity Provider ==

312

313

Placez le fichier au format XML fourni par l’IdP correspondant aux métadonnées de l’IdP dans le répertoire de votre choix.

314

315

(% class="box infomessage" %)

316

(((

317

**NB** : Le chemin absolu de ce fichier sera connu est sera renseigné comme valeur de l’attribut idPMetadataPath de la valve SAMLv2 (voir partie II.2).

318

)))

319

320

= Configuration des paramètres de sécurité =

321

322

Placez le fichier au format .properties correspondant aux paramètres de sécurité dans le répertoire de votre choix.

323

324

(% class="box infomessage" %)

325

(((

326

**NB** : Le chemin absolu de ce fichier sera connu est sera renseigné comme valeur de l’attribut securitySettingsPath de la valve SAMLv2 (voir partie II.2).

327

)))

328

329

Le tableau suivant présente les différentes propriétés possibles pour paramétrer la sécurité :

330

331

|Propriétés|Description

332

|(((

333

onelogin.saml2.sp.entityid

334

335

onelogin.saml2.sp.assertion_consumer_service.url

336

337

onelogin.saml2.sp.assertion_consumer_service.binding

338

339

onelogin.saml2.sp.single_logout_service.url

340

341

onelogin.saml2.sp.single_logout_service.binding

342

343

onelogin.saml2.sp.nameidformat

344

345

onelogin.saml2.sp.x509cert

346

347

onelogin.saml2.sp.privatekey

348

)))|(((

349

Propriétés relatives au Service Provider.

350

351

Les valeurs par défaut de ces propriétés sont automatiquement chargées côté SP.

352

353

Si besoin, il est possible de surcharger ces propriétés en les mentionnant dans le fichier properties.

354

355

La description plus détaillée de ces paramètres ainsi que les valeurs utilisées sont directement consultables dans le fichier de sécurité resources_samples\saml2.sec.properties fourni.

356

)))

357

|(% rowspan="2" %)onelogin.saml2.strict|Indique si le SP rejette tous les messages non cryptés ou non signés si le SP s’attend à ce qu’ils le soient.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.nameid_encrypted|Indique si le nameID du <samlp:logoutRequest> envoyé par le SP doit être crypté.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.authnrequest_signed|Indique si les messages <samlp:AuthnRequest> envoyés par ce SP sont signés. Les métadonnées indiquent cette information.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.logoutrequest_signed|Indique si les messages <samlp:logoutRequest> envoyés par ce SP sont signés.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.logoutresponse_signed|Indique si les messages <samlp:logoutResponse> envoyés par ce SP sont signés.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.want_messages_signed|Indique si les réponses doivent être signées

388

|(((

389

true Le message est requis d’être signé

390

391

false Le message n’est pas requis d’être signé

392

)))

393

|(% rowspan="2" %)onelogin.saml2.security.want_assertions_signed|Indique l’obligation des messages <samlp:Response>, <samlp:LogoutRequest> et <samlp:LogoutResponse> reçus par ce SP d’être signés.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.sign_metadata|Indique l’obligation des métadonnées de ce SP d’être signées.

400

|(((

401

true requiert la signature des métadonnées

false par défaut

)))

|(% rowspan="2" %)onelogin.saml2.security.want_assertions_encrypted|Indique l’obligation des assertions reçues par ce SP d’être cryptés.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.want_nameid_encrypted|Indique l’obligation du nameID reçu par le SP d’être crypté.

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.requested_authncontext|Contexte d’authentification

418

|(((

419

Vide si vous ne voulez qu’aucun contexte ne soit envoyé dans la requête AuthnRequest

420

421

Plusieurs valeurs séparées par des virgules sinon.

422

)))

423

|(% rowspan="2" %)onelogin.saml2.security.onelogin.saml2.security.requested_authncontextcomparison|Active la comparaison du contexte d’authentification

424

|'exact' par défaut

425

|(% rowspan="2" %)onelogin.saml2.security.want_xml_validation|Indique si le SP valide toutes les réponses XML reçues (Si true, la validation n’est effective que si cette propriété et la propriété ‘onelogin.saml2.strict’ valent aussi true).

|(((

true

false

)))

|(% rowspan="2" %)onelogin.saml2.security.signature_algorithm|Algorithme de hachage utilisé pour la signature.

432

|(((

433

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

434

435

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

436

437

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

438

439

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

440

441

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

442

)))

443

444

//__Tableau décrivant les paramètres de sécurité possible__//

445

446

(% class="box errormessage" %)

447

(((

448

Les champs grisés sont des champs proposés par la librairie onelogin mais qui ne sont pas encore mis en œuvre pour la valve SAMLv2 de DigDash donc non pris en compte.

449

)))

450

451

= Configuration de l’environnement Java =

452

453

L'extension JCE (Java Cryptography Extension) est requise. Vous pouvez télécharger la version jce-6, jce-7 ou jce-8, décompressez là dans le dossier suivant

454

455

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

456

457

|**Versions**|**Liens de téléchargement**

458

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

459

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

460

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

== Niveau de Logs ==

Vous pouvez personnaliser le niveau de log pour la valve d’authentification.

465

466

Par défaut, seuls les erreurs sont loguées. Si toutefois vous voulez avoir plus de détails sur le déroulé des actions et échanges entre les différentes entités, vous pouvez affecter la valeur ‘DEBUG’ au lieu de ‘ERROR’ dans le fichier log4j.properties qui a été importé dans le dossier lib de Tomcat.

467

468

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

469

470

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

471

472

= Authentification SAML2 côté Enterprise Studio =

473

474

Pour vous authentifier avec SAMLv2 côté Enterprise Studio, veuillez vous assurer d’avoir réalisé les actions suivantes

475

476

== Définitions du serveur et du domaine dans le fichier .jnlp ==

477

478

Vous pouvez, à l’instar du Dashboard, définir le serveur et le domaine sur lequel DigDash va s’appuyer.

479

480

Pour ce faire, modifier la fin du fichier digdash.jnlp dans le dossier d’installation **<DD Install>/apache-tomcat/webapps/adminconsole**

...

<application-desc main-class="commandline.CommandLineMain">

488

489

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

490

491

<argument>ddenterpriseapi</argument> (2)

492

493

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

494

495

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

496

497

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

498

499

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

...

</application-desc>

</jnlp>

(((

//__Extrait du fichier digdash.jnlp__//

510

)))

511

512

__**Attention**__** **: les arguments notées (1), (2), (3), (4), (5) ne doivent pas changer d’ordre.

513

514

Argument (1) : l’adresse du serveur DigDash ; variable selon votre installation

515

516

Argument (2) : le nom du domaine DigDash ; variable selon votre installation

517

518

Argument (5) : La méthode d’authentification ; External, obligatoirement

519

520

Argument (A) : argument facultatif, parfois nécessaire dans les cas de connexions SSL, HTTPS.

521

522

== Connexion au DigDash Enterprise Studio ==

523

524

Téléchargez et exécutez le .jnlp en vous rendant sur la page d’accueil dans la partie Enterprise Studio.

525

526

[[image:config_auth_saml2_fr_test_html_27c2ab581e0d9d7e.png||queryString="width=554&height=274" height="274" width="554"]]

527

528

Une fenêtre d’authentification doit apparaître avec la mire d’authentification de l’IdP.

529

530

Dans ce document, Salesforce est l’IdP que nous avons choisi pour illustrer nos exemples.

531

532

[[image:config_auth_saml2_fr_test_html_dff5c9e389ba1c1d.png||queryString="width=666&height=409" height="409" width="666"]]

533

534

//__Capture : mire avec formulaire d’authentification de l’IdP Salesforce__//

535

536

L’utilisateur devra rentrer ses données de connexion et s’il a bien été authentifié chez l’IdP et qu’il correspond bien à un utilisateur existant dans le LDAP DigDash, l’authentification aura réussi et la fenêtre attestera du succès de l’authentification.

537

538

[[image:config_auth_saml2_fr_test_html_6230a5f637fd4c54.png||queryString="width=612&height=376" height="376" width="612"]]

539

540

//__Capture : fenêtre d’une authentification réussie__//

541

542

La fenêtre se fermera automatiquement, puis le Studio débutera son chargement pour se lancer.

543

544

= Lexique =