eIDAS-Node and SAML Version 1.0 eIDAS-Node and SAML Version 1.0 Document history Version Date Modification reason Modified by 1.0 06/10/2017 Origination DIGIT Disclaimer This document is for informational purposes only and the Commission cannot be held responsible for any use which may be made of the information contained therein. References to legal acts or documentation of the European Union (EU) cannot be perceived as amending legislation in force or other EU documentation. The document contains a brief overview of technical nature and is not supplementing or amending terms and conditions of any procurement procedure; therefore, no compensation claim can be based on the contents of the present document. Copyright European Commission — DIGIT Page 2 of 59 eIDAS-Node and SAML Version 1.0 Table of contents DOCUMENT HISTORY ...................................................................................... 2 TABLE OF CONTENTS ...................................................................................... 3 LIST OF FIGURES ........................................................................................... 5 LIST OF TABLES ............................................................................................. 6 1. INTRODUCTION ....................................................................................... 7 1.1. Document aims ............................................................................... 7 1.2. Document structure ......................................................................... 7 1.3. Other technical reference documentation ............................................ 7 2. SAML OVERVIEW ..................................................................................... 9 2.1. Drivers of SAML Adoption ................................................................. 9 2.2. eID data flow example ................................................................... 10 3. EIDAS-NODE AND SAML XML ENCRYPTION................................................ 12 3.1. Requirement description ................................................................. 12 3.2. XML 1.1 Encryption Recommendation ............................................... 12 3.3. Overview of supported features ....................................................... 13 3.4. Encryption granularity .................................................................... 13 3.5. Encryption of an entire element ....................................................... 13 3.5.1. Encryption of the content elements of an element ................... 14 3.5.2. Encryption of the character content of an element .................. 14 3.5.3. Encryption of the entire document ........................................ 15 3.5.4. Symmetric key encryption ................................................... 15 3.6. SAML 2.0 AuthnResponse Assertion Encryption .................................. 16 3.6.1. Assertion encryption support by SAML 2.0 ............................. 16 3.6.2. Pseudo implementation of encryption of SAML Response .......... 17 3.6.3. Pseudo implementation of decryption of SAML Response .......... 17 3.6.4. Encryption configuration ..................................................... 18 3.6.5. eIDAS SAML 2.0 Encryption example .................................... 20 3.6.6. eIDAS SAML 2.0 Encryption and Signature ............................. 21 3.6.7. eIDAS SAML 2.0 Encryption with Signature example ............... 22 3.7. XML Encryption/Decryption implementation ....................................... 24 3.7.1. OpenSAML - XML Tooling .................................................... 24 3.7.2. Component dependencies .................................................... 25 3.7.3. Code snippet – Certification credential for encryption .............. 25 3.7.4. Code snippet – Data & key encryption parameters .................. 26 3.7.5. Code snippet – Set up open SAML encrypter .......................... 26 3.7.6. Code Snippet – Assertion encryption ..................................... 26 3.7.7. Code snippet – Manage specific namespace prefix ................... 26 3.7.8. Code snippet – Locate & construct the single certificate for decryption in the SAML Response ......................................... 27 3.7.9. Code snippet – Credential based on the certification for decryption......................................................................... 27 3.7.10. Code snippet – Assertion decryption ..................................... 28 Copyright European Commission — DIGIT Page 3 of 59 eIDAS-Node and SAML Version 1.0 3.8. Sources of further information ......................................................... 28 4. EIDAS NODE AND SAML METADATA ......................................................... 29 4.1. Presentation ................................................................................. 29 4.2. Use cases ..................................................................................... 29 4.2.1. Identification of eIDAS-Nodes .............................................. 29 4.2.2. Request messages verification ............................................. 30 4.2.3. Response messages verification ........................................... 30 4.2.4. Metadata exchange ............................................................ 31 4.3. Message format ............................................................................. 32 4.3.1. Metadata in SAML Requests & SAML Responses ...................... 32 4.3.2. Metadata profile for eIDAS-Nodes ......................................... 32 4.3.3. List of eIDAS metadata ....................................................... 33 4.4. Details of the metadata used in the eIDAS-Node ................................ 33 4.4.1. Support of dynamic and cached use of metadata .................... 33 4.4.2. Internal cache behaviour ..................................................... 34 4.4.3. Parametrisation of the metadata signing certificate ................. 34 5. EIDAS-NODE PROTOCOL ENGINE ............................................................. 36 5.1. Introduction .................................................................................. 36 5.2. Dependencies ............................................................................... 36 5.3. Configuration ................................................................................ 36 5.4. Using eIDAS SAML Engine (public interfaces) ..................................... 40 6. PROTOCOLENGINE CONFIGURATION ........................................................ 42 6.1. Obtaining a ProtocolEngine instance .............................................. 42 6.2. Configuring protocol engines ........................................................... 42 6.2.1. The DefaultProtocolEngineConfigurationFactory ...................... 43 6.2.2. Core properties .................................................................. 45 6.2.3. Signature Configuration ...................................................... 46 6.2.4. The encryption activation file ............................................... 48 6.2.5. ProtocolProcessor configuration ............................................ 49 6.2.6. The Attribute Registry ......................................................... 51 6.2.7. Clock configuration ............................................................. 58 6.2.8. Overriding the configuration with eidas.xml .......................... 58 7. REFERENCES ........................................................................................ 59 Copyright European Commission — DIGIT Page 4 of 59 eIDAS-Node and SAML Version 1.0 List of figures Figure 1: Use case – Citizen from one country accessing a service in another country . 10 Figure 2: Encryption of an entire element ............................................................. 13 Figure 3: Encryption of the content elements of an element .................................... 14 Figure 4: Encryption of the character content of an element .................................... 14 Figure 5: Encryption of the entire document .......................................................... 15 Figure 6: The architecture of SAML encryption ....................................................... 20 Figure 7: Component dependencies ..................................................................... 25 Copyright European Commission — DIGIT Page 5 of 59 eIDAS-Node and SAML Version 1.0 List of tables Table 1: List of eIDAS metadata .......................................................................... 33 Table 2: Metadata related parameters ................................................................... 34 Copyright European Commission — DIGIT Page 6 of 59 eIDAS-Node and SAML Version 1.0 1. Introduction This document is intended for a technical audience consisting of developers, administrators and those requiring detailed technical information on how to configure, build and deploy the eIDAS-Node application. This document describes the W3C recommendations and how SAML XML encryption is implemented and integrated in eID. Encryption of the sensitive data carried in SAML 2.0 Requests and Assertions is discussed alongside the use of AEAD algorithms as essential building blocks. 1.1. Document aims The aim of this document is to describe how the eIDAS-Node implements SAML. 1.2. Document structure This document is divided into the following sections: Chapter 1 − Introduction this section. Chapter 2 − SAML Overview provides an overview of SAML