Main content

Wat zijn SAML certificaten en metadata en hoe werkt het?

Security Assertion Markup Language (SAML) is een gestandaardiseerde aanpak voor het veilig uitwisselen van authenticatie- en autorisatiegegevens van gebruikers tussen verschillende organisaties. SAML wordt gebruikt in de aansluiting tussen een dienstaanbieder en DigiD. 

Voordat een SAML-aansluiting tot stand gebracht kan worden, moeten dienstaanbieder en DigiD elkaar eenmalig van configuratiegegevens over de aansluiting voorzien. Dit gebeurt via twee zogenaamde metadata bestanden: één van de dienstaanbieder en één van DigiD. Hierin wordt aangeven welke locaties van diensten (endpoints/URL's) en certificaten gebruikt worden voor de aansluiting. Voor een uitgebreide beschrijving van de SAML-aansluiting wordt verwezen naar de Koppelvlakspecificatie DigiD SAML Authenticatie

De metadata van de dienstaanbieder wordt via het wijzigingsformulier van DigiD aangeboden aan Logius in de vorm van een XML-bestand in het door de SAML2.0 standaard voorgeschreven formaat.

De dienstaanbieder moet de metadata gesigned aanleveren. Voor de signature moet daarbij het PKIo certificaat worden gebruikt dat in de metadata is opgenomen als signing certificaat. Dit geldt ook voor aansluitingen op de preproductie-omgeving van DigiD. Om ervoor te zorgen dat er geen gegevensuitwisseling plaats kan vinden tussen de preproductie-omgeving en de productie-omgeving moet het certificaat van de preproductie-omgeving een ander zijn dan van de productie-omgeving. 

Logius controleert de metadata en de certificaten van een dienstaanbieder op deze uitgangspunten alvorens deze op te nemen in de SAML configuratie van DigiD.

Welke certificaten moeten gebruikt worden voor SAML signing?

Er moet voor SAML signing een PKIo Private Root CA - G1 certificaat (met daarin het OIN van de organisatie) gebruikt worden. Om ervoor te zorgen dat er geen gegevensuitwisseling plaats kan vinden tussen de preproductie-omgeving en de productie-omgeving moet het certificaat van de preproductie-omgeving een ander zijn dan van de productie-omgeving

Dit is het makkelijkste te realiseren door een certificaat te gebruiken voor een specifiek (sub)domein (Common Name CN) van uw organisatie bijv. saml-preprod.organisatie.nl voor de preproductie-omgeving en een tweede certificaat bijvoorbeeld saml.organisatie.nl voor de productie-omgeving. Dit (sub)domein hoeft niet opgenomen te zijn in DNS (en dus niet vindbaar te zijn op Internet). 

Er mag geen overlap zijn in de Subject Alternative Names (SAN's) van de certificaten, omdat dit ook een ongewenste gegevensuitwisseling tussen omgevingen kan veroorzaken.

Welk certificaat moet gebruikt worden voor 2-zijdig TLS in het SAML koppelvlak?

Er moet voor 2-zijdig TLS een PKIo Private Root CA - G1 certificaat (met daarin het OIN van de organisatie) gebruikt worden. 

Omdat dit certificaat alleen maar aangeeft welke organisatie het betreft (OIN), kan hetzelfde certificaat gebruikt worden voor zowel de productie-omgeving als de preproductie-omgeving van DigiD. Hetzelfde certificaat kan dus gebruikt worden bij het opzetten van de verbinding met de server was-preprod1.digid.nl én met was.digid.nl. Ook kan hetzelfde certificaat gebruikt worden voor meerdere aansluitingen op DigiD. 

Ook is het niet van belang op welk (sub)domein het certificaat uitgegeven is (de velden Common Name CN en Subject Alternative Name SAN). Voor 2-zijdig TLS in het SAML koppelvlak met DigiD kan er dus gebruik gemaakt worden van een certificaat dat reeds aanwezig is voor een ander koppelvlak, zelfs als dat een koppelvlak niet met DigiD is. Er kan dus bijvoorbeeld een certificaat gebruikt worden met als CN het (sub)domein backoffice.organisatie.nl, en zelfs als dit domein niet is opgenomen in DNS (en dus niet vindbaar is op Internet). Wel moet er goed gekeken worden naar de risico's als een certificaat voor meerdere doeleinden wordt gebruikt: als het certificaat niet meer werkt (verlopen of ingetrokken), dan worden meerdere verbindingen getroffen. 

Voor een leverancier van meerdere aansluitingen op DigiD, bijvoorbeeld een leverancier die voor meerdere organisaties de aansluitingen beheert, is het mogelijk om een certificaat op naam van de leverancier te gebruiken voor 2-zijdig TLS. Een certificaat met als CN het (sub)domein leverancier.nl is dus ook mogelijk, zolang het maar een PKIo Private Root CA - G1 certificaat is (met daarin het OIN van de leverancier). Hiermee kan in sommige gevallen een efficiëntere aansluiting op DigiD gemaakt worden. 

Hoeveel verschillende PKIo certificaten moeten gebruikt worden voor de SAML-aansluiting met DigiD?

Er moeten minimaal twee verschillende PKIo certificaten gebruikt worden om een SAML-aansluiting met DigiD te kunnen realiseren.

Het eerste certificaat kan voor zowel SAML signing van de productie-omgeving gebruikt worden, alsmede voor 2-zijdig TLS van beide omgevingen. Het tweede certificaat kan dan voor SAML signing van de preproductie-omgeving gebruikt worden. Voor 2-zijdig TLS kan eventueel een derde certificaat gebruikt worden, maar dit is optioneel.

In een overzicht ziet dat er als volgt uit:

  Productie-omgeving Preproductie-omgeving
SAML signing Certificaat 1
bijv. saml.organisatie.nl
Certificaat 2
bijv. saml-preprod.organisatie.nl
2-zijdig TLS Certificaat X (1, 2 of 3)
3: bijv. backoffice.organisatie.nl
of leverancier.nl
Certificaat X (1, 2 of 3)
3: bijv. backoffice.organisatie.nl
of leverancier.nl

Hoe kan ik de werking van 2-zijdig TLS vanuit de applicatie testen?

De werking van 2-zijdig TLS kan getest worden vanaf de server / omgeving waar de private sleutel van het certificaat beschikbaar is. Door gebruik te maken van een HTTP-client (commandline-software zoals cURL, in sommige gevallen ook een browser) kan de verbinding met was-preprod1.digid.nl getest worden en dient het certificaat meegegeven te worden in de verbinding. Afhankelijk van de respons van de DigiD applicatieserver kan bepaald worden of het certificaat op de juiste wijze wordt gebruikt voor 2-zijdig TLS. 

De verschillende test-scenario's zijn hieronder als voorbeeld uitgewerkt bij gebruik van cURL vanaf de commandline. Testscenario 5 resulteert in een "geslaagde" verbinding met DigiD.

Update

4 januari 2022: testscenario’s aangevuld.

Nr Testscenario cURL commando Output van cURL Resultaat
1 Geen certificaat meegeven in de verbinding curl -v https://was-preprod1.digid.nl/ 302 Moved Temporarily Redirect naar www.digid.nl
2 Verkeerde certificaat of private sleutel meegeven in de verbinding curl --key verkeerde.key --cert verkeerde.crt -v https://was-preprod1.digid.nl/ curl: (58) unable to set private key file: 'verkeerde.key' type PEM Er wordt geen verbinding opgezet
3 Een niet PKIo certificaat meegeven in de verbinding curl --key geenPKIo.key --cert geenPKIo.crt -v https://was-preprod1.digid.nl/ curl: (56) OpenSSL SSL_read: connection reset by peer
* Afhankelijk van het OS en de SSL library kan hier een andere melding komen. Het resultaat is dat de verbinding wordt afgebroken.
Verbinding wordt afgebroken
4 Een PKIo certificaat meegeven in de verbinding dat niet geldig is curl --key ongeldigePKIo.key --cert ongeldigePKIo.crt -v https://was-preprod1.digid.nl/ curl: (56) OpenSSL SSL_read: connection reset by peer
* Afhankelijk van het OS en de SSL library kan hier een andere melding komen. Het resultaat is dat de verbinding wordt afgebroken.
Verbinding wordt afgebroken
5 Een PKIo certificaat meegeven in de verbinding dat wel geldig is.  curl --key goedePKIo.key --cert goedePKIo.crt -v https://was-preprod1.digid.nl/ 404 Not Found Foutpagina (omdat het domein zonder URI wordt geraadpleegd)