Afsprakenstelsel eherkenning. Koppelvlak DV-HM. Versie 1.4

Afsprakenstelsel eHerkenning Koppelvlak DV-HM

Versie 1.4

1

Document informatie

2

Colofon

3

Auteur

Status

Beheerorganisatie Afsprakenstelsel eHerkenning

Definitief

Project

Datum

Afsprakenstelsel eHerkenning

28 april 2012

Organisatie

Classificatie

Stichting ICTU

Openbaar

Titel

Versie

Afsprakenstelsel eHerkenning - Koppelvlak DV-HM

1.4

Historie Datum

Versie

29-03-10

0.8def

06-09-10

1.0

Vorm wijzigingen en doorvoeren verschillende RFCs

Ter goedkeuring

Projectbureau

17-12-10

1.0a

RFCs verwerkt conform besluit Kernteam 6 december

Definitief

Projectbureau

17-06-11

1.1

RFCs verwerkt conform besluit kernteam 31 mei

Definitief

Projectbureau

12-11-11

1.2

RFCs verwerkt conform besluit kernteam 11 oktober

Definitief

Projectbureau

23-12-11

1.3

RFCs verwerkt conform besluit kernteam 13 december

Definitief

Projectbureau

05-01-12

1.3a

Correcties op RFC102, RFC105 en RFC124 doorgevoerd

Definitief

Projectbureau

RFCs verwerkt conform besluit kernteam 20 maart

Definitief

Beheerorganisatie

28/04/12 1.4

4

Wijziging

Verwerkt door

T.b.v. proefProjectbureau implementaties

Distributielijst Datum

Distributie Kernteam, launching customers en publicatie op eherkenning.nl

5

Status

Presentatie

Versie 1.4

Goedkeuring Datum

Naam

Versie

Afsprakenstelsel eHerkenning - Koppelvlak DV-HM | Datum:28 april 2012 | Versie: 1.4 |

2/43

20/03/12 Alle RFCs voor versie 1.4 goedgekeurd door kernteam

1.4


3/43

Inhoud 1 1.1 1.2 1.3 1.4 1.5

Inleiding.....................................................................................................................................................6 Doel en doelgroep van dit document........................................................................... 6 Leeswijzer................................................................................................................... 6 Begrippenlijst.............................................................................................................. 6 Terminologie.............................................................................................................. 6 Typografie.................................................................................................................. 7

2 2.1 2.2 2.2.1 2.2.2 2.2.2.1 2.2.2.2 2.2.3 2.2.4 2.3 2.4 2.5 2.5.1 2.6 2.7 2.8

Algemene eisen...................................................................................................................................... 8 Alternatieve koppelvlakken en/of bindings.................................................................. 8 Gebruik van SAML 2.0................................................................................................. 8 SAML Web Browser SSO Profile.................................................................................... 8 Bindings..................................................................................................................... 8 HTTP POST Binding.................................................................................................... 9 Alternatieve binding................................................................................................... 9 Relay State.................................................................................................................. 9 Namespace aliases...................................................................................................... 9 HTTP Headers............................................................................................................. 9 Optionele elementen en attributen............................................................................ 10 Sessies...................................................................................................................... 10 Uitloggen.................................................................................................................. 10 Versionering............................................................................................................. 10 Taalvoorkeur............................................................................................................. 11 Character set en encoding......................................................................................... 11

3 3.1 3.2 3.3 3.4

Technische informatiebeveiligingseisen...................................................................................12 Beveiliging verbinding............................................................................................... 12 Signing berichten...................................................................................................... 12 Gebruik PKIoverheid gegevens.................................................................................. 13 Synchronisatie systeemklokken................................................................................. 13

4 4.1 4.2 4.3

Foutafhandeling...................................................................................................................................14 Annuleren................................................................................................................. 14 Foutief opgemaakte berichten................................................................................... 14 Functioneel ontoereikende berichten......................................................................... 14

5 5.1 5.2 5.2.1 5.2.2 5.3 5.3.1 5.3.2 5.3.2.1 5.3.2.2

Berichtenspecificaties....................................................................................................................... 16 AuthnRequest (1)...................................................................................................... 16 Response (2)............................................................................................................. 18 Verklaring over authenticatie..................................................................................... 19 Verklaring over bevoegdheid..................................................................................... 20 Alternatieve binding.................................................................................................. 20 HTTP Redirect binding............................................................................................... 21 HTTP Artifact binding................................................................................................ 21 ArtifactResolve......................................................................................................... 21 ArtifactResponse...................................................................................................... 22

6 6.1 6.2

Dienstencatalogus.............................................................................................................................. 23 Formaat.................................................................................................................... 23 Publicatie.................................................................................................................. 24

7

Attribuutcatalogus..............................................................................................................................25

8

Metadata..................................................................................................................................................27


4/43

8.1

Formaat metadata .................................................................................................... 27

9 9.1 9.1.1 9.1.2 9.1.3 9.1.4 9.1.5 9.1.6 9.2 9.2.1 9.2.2 9.2.3 9.2.4 9.2.4.1 9.3 9.3.1 9.3.2 9.3.3 9.3.4 9.4

Data-elementen.................................................................................................................................... 30 OIN formaat.............................................................................................................. 30 FI-nummer................................................................................................................ 30 KvK nummer............................................................................................................. 30 Vestigingsnummer (nieuwe formaat)......................................................................... 30 Vestigingsnummer (oude formaat)............................................................................ 31 DigiKoppeling registry.............................................................................................. 31 Buitenlandse registers............................................................................................... 31 Identificerende kenmerken........................................................................................ 31 Betrouwbaarheidsniveau........................................................................................... 32 ServiceID................................................................................................................... 32 EntityID..................................................................................................................... 32 Pseudoniemen.......................................................................................................... 33 Specifiek pseudoniem............................................................................................... 33 SAML Attributen........................................................................................................ 34 EntityConcernedID.................................................................................................... 34 EntityConcernedSubID 1.2......................................................................................... 35 OldEntityConcernedSubID 1.2.................................................................................... 35 ServiceID................................................................................................................... 35 URL of POST variabele: EherkenningPreferredLanguage.............................................. 35

10

Bijlage XML Schema dienstencatalogus.....................................................................................37

11 11.1 11.2

Bijlage voorbeeld berichten............................................................................................................39 AuthnRequest........................................................................................................... 39 Response.................................................................................................................. 41

12 12.1

eHerkenning XML Schema extensions........................................................................................43 XML schema attribute extension................................................................................ 43


5/43

6

1

Inleiding

7

Dit document maakt deel uit van het afsprakenstelsel eHerkenning. Het kan niet los worden

8

gezien van de andere documenten van het afsprakenstelsel. Voor een algemene introductie op, en

9

een overzicht van alle documenten binnen eHerkenning wordt de lezer van dit document

10

aangeraden eerst het document [eHerkenning - Algemene introductie] te lezen.

11

1.1

12

Dit document beschrijft het koppelvlak tussen de dienstverlener en de eHerkenningsmakelaar. Het

Doel en doelgroep van dit document

13

is bedoeld voor iedereen die behoefte aan de meest gedetailleerde technische specificaties.

14

1.2

15

Het vervolg van dit document ziet er als volgt uit. Hoofdstuk 2 beschrijft de algemene eisen voor

Leeswijzer

16

het koppelvlak. Hoofdstuk 3 beschrijft de technische informatiebeveiligingseisen. In hoofdstuk 4

17

wordt de foutafhandeling beschreven. Hoofdstuk 5 bevat de berichtenspecificaties. Hoofdstuk 6

18

beschrijft de dienstencatalogus en hoofdstuk 8 de metadata. In hoofdstuk 9 wordt een overzicht

19

gegeven van de gebruikte data-elementen. Het document sluit af met enkele bijlagen waar vanuit

20

de tekst naar verwezen wordt.

21

1.3

22

Binnen eHerkenning wordt één begrippenlijst gehanteerd. Zie de bijlage in document

Begrippenlijst

23

[eHerkenning - Algemene introductie]. In deze lijst zijn enkelvoudsvormen van zelfstandige

24

naamwoorden en werkwoorden opgenomen. Waar in dit document de werkwoordsvorm van deze

25

zelfstandige naamwoorden wordt gehanteerd, heeft deze dezelfde betekenis als de gedefinieerde

26

zelfstandige naamwoorden. Dat zelfde geldt ook andersom: waar in dit document de

27

zelfstandige-naamwoords-vorm van een werkwoord wordt gehanteerd, heeft deze dezelfde

28

betekenis als het gedefinieerde werkwoord.

29

1.4

30

Ter wille van de leesbaarheid van de tekst is overal ‘hij’ geschreven waar ‘hij of zij’ bedoeld wordt.

31

De woorden “MOET”, “MAG NIET”, “ZOU MOETEN”, “ZOU NIET MOETEN”, en “MAG” in dit document

32 33

Terminologie

moeten worden geïnterpreteerd gelijk aan hun Engelstalige equivalenten (“MUST", "MUST NOT / SHALL NOT", "SHOULD", "SHOULD NOT", and "MAY") als beschreven in RFC 2119

34

(http://www.ietf.org/rfc/rfc2119.txt). Waar deze exacte termen bedoeld zijn worden ze in hoofd-

35

letters weergegeven. De betekenis van deze woorden is:

36

•

MOET: een absolute vereiste


6/43

37

•

MAG NIET: een absoluut verbod

38

•

ZOU MOETEN: sterke wens, tenzij er valide reden is in specifiek geval af te wijken

39

•

ZOU NIET MOETEN: ongewenst, tenzij er valide reden is om het in specifiek geval toe te laten

40

MAG: een vrije keuze, een optie

41

•

42

1.5

43

In de meer technische delen van de documentatieset worden de woorden “MOET”, “MAG NIET”,

44

“ZOU MOETEN”, “ZOU NIET MOETEN”, en “MAG” altijd in hoofdletters genoteerd.

Typografie


7/43

45

2

Algemene eisen

46

Het in dit document beschreven koppelvlak wordt gebruikt voor de implementatie van de use case

47

“authenticatie handelende dienstafnemer” en MOET (m.u.v. paragraaf 2.2.2.2 en 5.3) door elke

48

eHerkenningsmakelaar worden geïmplementeerd en worden aangeboden aan haar gebruikers, de

49

dienstverleners1.

50

2.1

51

Een eHerkenningsmakelaar MAG ook andere koppelvlakken en/of bindings implementeren en

Alternatieve koppelvlakken en/of bindings

52

aanbieden dan zijn beschreven in dit document, maar MOET dan voor gebruik aan de

53

beheerorganisatie aantonen dat de

54

beveiliging en functionaliteit van minimaal hetzelfde niveau zijn als die van het in dit document

55

beschreven koppelvlak en dat het interne pseudoniem niet wordt gedeeld.

56

Onder beveiliging van hetzelfde niveau wordt verstaan dat:

57

•

gebruik gemaakt wordt van asymmetrische vercijfering op basis van een PKI

58

•

sleutellengtes van minimaal 2048 bit worden afgedwongen

59

•

minimaal SHA256 wordt gebruikt als hashing algorithme

60

•

maatregelen zijn genomen tegen replay aanvallen

61

•

berichten/verklaringen beperkt houdbaar zijn

62

Tevens MOET de eHerkenningsmakelaar voor gebruik een beschrijving van alle in het alternatieve

63

koppelvlak aan de dienstverlener te leveren gegevens aanleveren bij de beheerorganisatie.

64

2.2

65

Dit koppelvlak maakt gebruik van SAML 2.0. Een dienstverlener wordt gezien als een service

66

provider. Een eHerkenningsmakelaar wordt gezien als een identity provider.

67

2.2.1

68

Voor het in dit document beschreven koppelvlak MOET het SAML Web Browser SSO Profile worden

Gebruik van SAML 2.0

SAML Web Browser SSO Profile

69

gebruikt. Voor het uitvragen van attributen wordt optioneel gebruik gemaakt van een extensie.

70

2.2.2

71

Binnen SAML kunnen verschillende bindings worden toegepast om berichten te transporteren

72

tussen partijen. 1

Bindings

Dit gaat lock-in tegen en stelt zgn. middleware leveranciers generieke stukken software te bouwen die bij alle eHerkenningsmakelaars te gebruiken zijn.


8/43

73

2.2.2.1

HTTP POST Binding

74

Voor het in dit document beschreven koppelvlak MOET elke eHerkenningsmakelaar de HTTP POST

75

binding2 implementeren en aanbieden aan haar klanten, de dienstverleners. Een

76

eHerkenningsmakelaar MAG ook andere bindings implementeren en aanbieden.

77

2.2.2.2

78

Om dienstverleners tegemoet te komen wordt in dit document ook een alternatieve, optionele

79

binding beschreven. Dit is de binding die gedurende proefimplementaties is gebruikt voor het

Alternatieve binding

80

koppelvlak tussen dienstverlener en eHerkenningsmakelaar. eHerkenningsmakelaars MOGEN deze

81

binding implementeren en aanbieden.

82

De beschreven alternatieve binding is een combinatie van de HTTP Redirect3 en HTTP Artifact4

83

binding gebruiken, waarbij de vraag wordt gesteld met een HTTP Redirect binding en het

84

antwoord wordt gegeven met een HTTP Artifact binding.

85

De recommendations met betrekking tot het samenstellen van een artifact (paragraaf 3.6.4 van de

86

SAML 2.0 binding specificatie5) MOETEN zijn geïmplementeerd.

87

2.2.3

88

Elk SAML request bericht MAG RelayState data bevatten. De response op een SAML request met

89

RelayState data MOET deze RelayState data ook bevatten. De inhoud van de RelayState MAG NIET

Relay State

90

groter zijn dan 80 byte en MOET door de partij die de RelayState creëert worden beschermd tegen

91

wijzigingen.

92

2.2.4

93

Wellicht ten overvloede wordt opgemerkt dat het partijen vrij staat te kiezen welke aliases worden

Namespace aliases

94

gebruikt voor de afkorting van namespaces in tags.

95

2.3

96

Voor alle content die naar een browser van een handelende natuurlijk persoon wordt gestuurd

97

HTTP Headers

MOETEN de volgende HTTP headers worden gebruikt:

98

•

Cache-Control met waarde "no-cache, no-store"

99

•

Pragma met waarde "no-cache"

2 3 4 5

urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact http://docs.oasis-open.org/security/saml/v2.0/saml-bindings-2.0-os.pdf Afsprakenstelsel eHerkenning - Koppelvlak DV-HM | Datum:28 april 2012 | Versie: 1.4 |

9/43

100

2.4

Optionele elementen en attributen

101

Optionele elementen en attributen MOGEN worden opgenomen in berichten. Deze elementen

102

MOETEN dan worden gevuld conform specificaties en MOGEN dus NIET leeg zijn.

103

2.5

104

Deelnemers MOGEN NIET een sessie van de handelende natuurlijk persoon bijhouden die langer

Sessies

105

duurt dan strikt noodzakelijk voor het uitvoeren van de use case.

106

Uitsluitend t.b.v. Single Sign-On en dan uitsluitend t.b.v. proof-of-concept/pilot-achtige situaties

107

MOGEN een eHerkenningsmakelaar, authenticatiedienst en machtigingenregister een sessie voor

108

de duur van maximaal 60 minuten bijhouden. In deze sessie MOGEN de volgende gegevens

109 110

worden bijgehouden:

een eHerkenningsmakelaar houdt gebruikersvoorkeuren (gekozen authenticatiedienst en

•

gekozen machtigingenregister) bij.

111 112

een authenticatiedienst houdt de identiteit van de handelende natuurlijk persoon bij. Op

•

113

basis van deze sessie MAG de authenticatiedienst direct een nieuwe verklaring over de

114

authenticatie afgeven.

115

een machtigingenregister houdt gebruikersvoorkeuren (gekozen te vertegenwoordigen

•

belanghebbende) bij.

116 117

Het ligt voor de hand dat dienstverleners o.b.v. de van eHerkenning verkregen verklaring over de

118

authenticatie van het bedrijf een sessie met de handelende natuurlijk persoon starten.

119

2.5.1

120

Deelnemers MOGEN een handelende natuurlijk persoon de mogelijkheid geven uit te loggen.

Uitloggen

121

Dienstverleners MOETEN zelf maatregelen nemen om na een bepaalde mate van inactiviteit de

122

handelende natuurlijk persoon automatisch uit te loggen.

123

2.6

124

Omdat verschillende versies van het afsprakenstelsel op koppelvlakniveau van elkaar moeten

125

kunnen worden onderscheiden MOET gebruik gemaakt worden van versionering van de berichten

Versionering

126

in het geïmplementeerde koppelvlak. Omdat in de SAML 2.0 berichten hiervoor geen veld

127

beschikbaar is en het niet wenselijk is hiervoor een extensie in de berichten te gebruiken MOETEN

128

deelnemers de URL waarop SAML berichten kunnen worden aangeboden in de gepubliceerde

129

metadata koppelen aan een versie van het afsprakenstelsel. Voor twee verschillende versies van

130

het afsprakenstelsel MAG dus NIET dezelfde URL worden gebruikt. Bijv.

Afsprakenstelsel eHerkenning - Koppelvlak DV-HM | Datum:28 april 2012 | Versie: 1.4 | 10/43

131

http://www.deelnemer.nl/SAML-endpoint/v1.0/

132

Zie ook hoofdstuk 8.

133

2.7

134

Binnen eHerkenning is het mogelijk om de taal voorkeur van de handelende natuurlijk persoon

135

door te geven zodat de dialoog in deze taal kan worden gevoerd. Omdat in de SAML 2.0 berichten

Taalvoorkeur

136

hiervoor geen veld beschikbaar is en het niet wenselijk is hiervoor een extensie in de berichten te

137

gebruiken MAG EherkenningPreferredLanguage als query variabele in de URL of als POST variabele

138

worden meegegeven. Zie ook paragraaf 9.4.

139

2.8

140

Voor alle berichten MOET gebruik worden gemaakt van de Unicode character set in UTF-8

141

Character set en encoding

encoding.


142

3

Technische informatiebeveiligingseisen

143

Dit hoofdstuk beschrijft de eisen waarmee de maatregelen die in het kader van

144

informatiebeveiliging zijn getroffen worden geïmplementeerd.

145

3.1

146

Voor alle verbindingen tussen twee systemen gelden de volgende eisen:

Beveiliging verbinding

147

•

Alle verbindingen MOETEN gebruik maken van SSL 3.0 of TLS.

148

•

In het WS-I basic security profile6 worden enkele cipher suites afgeraden. Deze MOGEN NIET voor SSL of TLS worden gebruikt.

149 150

•

Voor SSL of TLS ZOU een deelnemer een PKIoverheid G2 SSL certificaat MOETEN gebruiken.

151

Wanneer geen PKIoverheid G2 SSL certificaat wordt gebruikt MOET een deelnemer een EV

152

SSL certificaat met een sleutellengte van ten minste 2048 bits gebruiken. Het (extended) key usage van het gebruikte certificaat MOET gebruik voor SSL/TLS toestaan..

153 154

•

Voor SSL of TLS ZOU een dienstverlener een EV SSL certificaat met een sleutellengte van ten

155

minste 2048 bits MOETEN gebruiken. Een dienstverlener MOET een SSL certificaat met een

156

sleutellengte van ten minste 1024 bits gebruiken.

157

N.B. Het gebruik van andere SSL certificaten dan PKIoverheid G2 certifcaten zal op termijn niet

158

meer worden toegestaan.

159

3.2

160

Om authenticiteit, integriteit en onweerlegbaarheid te garanderen MOET elk bericht dat is

Signing berichten

161

beschreven in dit document worden voorzien van een elektronische handtekening van de

162

verzender van het bericht. De ontvanger van een bericht MOET alle elektronische handtekeningen

163

in het bericht valideren alvorens het bericht verder te verwerken.

164

Voor het genereren van een elektronische handtekening gelden de volgende eisen:

165

•

De elektronische handtekening MOET worden gezet over het hele bericht met de Enveloped Signature Transform7.

166 167

•

Canonicalization MOET gebeuren volgens de exclusive c14n methode 8.

168

•

Digests MOETEN worden berekend met het SHA-256 algoritme.

6 7 8

http://www.ws-i.org/Profiles/BasicSecurityProfile-1.0.html http://www.w3.org/2000/09/xmldsig#enveloped-signature http://www.w3.org/TR/xml-exc-c14n/


169

•

De SignatureValue MOET worden berekend met het RSA-SHA256 algoritme.

170

•

Voor het ondertekenen van berichten MOET een deelnemer een PKIoverheid G2 certificaat met een sleutellengte van ten minste 2048 bits gebruiken. Het (extended) key usage van

171

het gebruikte certificaat MOET gebruik voor signing toestaan..

172 173

Voor het ondertekenen van berichten MOET een dienstverlener een PKIoverheid G1

•

174

certificaat met een sleutellengte van ten minste 1024 bits of een PKIoverheid G2 certificaat

175

met een sleutellengte van ten minste 2048 bits gebruiken.

176

De handtekening MOET een keyinfo element bevatten, met daarin een KeyName. De

•

KeyName MOET overeenkomen met een KeyName genoemd in de metadata van de

177 178

verzender voor de betreffende rol. De handtekening MAG NIET andere keyinfo bevatten

179

(zoals X509Data).

180

3.3

181

Om goed gebruik te kunnen maken van PKIoverheid MOETEN ontvangers van berichten voldoen

182

aan de eisen voor de ontvangende partij zoals beschreven in het PKIoverheid Programma van

183

Gebruik PKIoverheid gegevens

Eisen. Hierbij zijn de volgende aspecten van belang:

184

•

Het Stamcertificaat “Staat der Nederlanden Root CA – G2” 9 vertrouwen.

185

•

Alle Domeincertificaten en alle CSP-certificaten10 kennen en vertrouwen.

186

•

De PKIoverheid CRL11 met regelmaat raadplegen.

187

3.4

188

In het netwerk wordt gewerkt met Coordinated Universal Time, UTC genaamd. Alle

189

tijdsaanduidingen in de berichten worden opgemaakt in de vorm yyyy-mm-ddThh:mm:ssZ. (De

Synchronisatie systeemklokken

190

T(time) en Z(zulu) zijn vaste waarden).

191

Elke deelnemer MOET door middel van synchronisatie met een betrouwbare nauwkeurige tijdbron

192

de afwijking van de systeemtijd minder of gelijk aan 2 seconden laten zijn.

9 10 11

Zie http://www.pkioverheid.nl Zie http://www.pkioverheid.nl Zie http://crl.pkioverheid.nl


193

4

Foutafhandeling

194

Deze paragraaf beschrijft de wijze waarop fouten MOETEN worden afgehandeld in het netwerk,

195

opdat de gebruikers en de deelnemers naar voldoening worden geïnformeerd en bediend. Bij

196

foutafhandeling wordt het principe gehanteerd dat fouten worden afgehandeld daar waar de fout

197

binnen het netwerk optreedt.

198

4.1

199

In de normale berichtenflow kan de handelende natuurlijk persoon het proces afbreken door te

Annuleren

200

klikken op de “annuleren” knop. In het hoofdstuk Use Cases worden de scenario's geëxpliciteerd

201

waarbij een eindgebruiker op de “annuleren” knop kan drukken.

202

Als de gebruiker annuleert MOET de deelnemer de gebruiker automatisch terugsturen naar de

203

verzender, met een geldig SAML bericht, met een StatusCode Value = AuthnFailed. Een verzender

204

MAG een StatusMessage opnemen (bijvoorbeeld “Authentication Cancelled”).

205

4.2

206

Wanneer een partij een foutief opgemaakt bericht ontvangt dan MOET de deelnemer het proces

207

direct afbreken. Onder een foutief opgemaakt bericht wordt (onder andere) verstaan: ongeldige

Foutief opgemaakte berichten

208

XML, geen SAML, niet valide handtekening, ongeldige digest en verkeerde versie SAML.

209 210

De ontvanger MOET de handelende natuurlijk persoon melden dat een onherstelbare fout is opgetreden.

211

De ontvangende partij MOET de fout in onderzoek nemen en MOET de verzender op hoogte

212

stellen dat er een fout is opgetreden. De verzender MOET de fout in onderzoek nemen.

213

4.3

214

Er kan een vraag aan een deelnemer worden gesteld, die functioneel ongeldig is. Bijvoorbeeld

Functioneel ontoereikende berichten

215

omdat een verkeerde issuer wordt opgevoerd. Wanneer een partij een bericht ontvangt dat

216

functioneel niet volgens specificaties is dan MOET de ontvangende partij het proces afbreken. De

217

ontvangende partij MOET de gebruiker automatisch terugsturen naar de verzender, met een

218

geldig SAML bericht, met een SAML status code Requester , en een firstlevel status code

219

RequestDenied. De ontvanger MOET in de SAML status message aangeven wat het probleem is

220

(bijvoorbeeld “missing or unknow issuer”).

221

Er kan een vraag aan een deelnemer worden gesteld, waar een deelnemer geen antwoord op Afsprakenstelsel eHerkenning - Koppelvlak DV-HM | Datum:28 april 2012 | Versie: 1.4 | 14/43

222

heeft. Bijvoorbeeld omdat een betrouwbaarheidsniveau wordt gevraagd waar een AD niet aan kan

223

voldoen. Wanneer een partij een bericht ontvangt dat functioneel niet door de partij kan worden

224

afgehandeld dan MOET de ontvangende partij het proces afbreken. De ontvangende partij MOET

225

de gebruiker automatisch terugsturen naar de verzender, met een geldig SAML bericht, met een

226

SAML status code Responder, en een firstlevel status code RequestUnsupported. De ontvanger

227

MOET in de SAML status message aangeven wat het probleem is (bijvoorbeeld “level not

228

supported”).

229

Wanneer een partij een bericht ontvangt dat te oud is (issueinstant), of dit bericht niet verwacht

230

op dat moment (onbekend inresponseto) in het proces, dan MOET de ontvangende partij het

231

proces afbreken. De ontvangende partij MOET de gebruiker automatisch terugsturen naar de

232

verzender, met een geldig SAML bericht, met een SAML status code Responder, en een firstlevel

233

status code RequestDenied. De ontvanger MOET in de SAML status message aangeven wat het

234

probleem is (bijvoorbeeld “message invalid”).

235

De verzender MOET deze fouten in onderzoek nemen. De verzender stelt de gebruiker op de

236

hoogte van de reden van het mislukken. De verzender MAG de gebruiker een alternatief bieden.


237

5

Berichtenspecificaties

238

Dit hoofdstuk beschrijft de berichten van het hier beschreven koppelvlak.

239

De use case “authenticatie handelende dienstafnemer” wordt in het hier beschreven koppelvlak

240

ingevuld met en SAML 2.0 AuthnRequest en Response.

Figuur 1: Sequence diagram DV-HM 241

De specifieke invulling van deze berichten wordt hieronder beschreven. Detailinformatie over de

242

inhoud van velden kan worden gevonden in hoofdstuk 9.

243

Wanneer in de beschrijving van een bericht de kolom invulling begint met “SAML:” betekent dit dat

244

dit een standaard invulling is. Als de invulling begint met “eHerkenning:” betekent dit dat het om

245

een eHerkenning specifieke invulling gaat.

246

5.1

247

Zie paragraaf 11.1 voor een voorbeeld.

AuthnRequest (1)

Data element

Invulling

@ID

SAML: Uniek kenmerk van het bericht

@Version

SAML: Versie van het SAML protocol. De waarde MOET “2.0” zijn.

@IssueInstant

SAML: Tijd waarop het bericht is aangemaakt

@Destination

SAML: URL van de eHerkenningsmakelaar waarop het bericht wordt aangeboden. MOET overeenkomen met de metadata van de eHerkenningsmakelaar.

@Consent

eHerkenning: MAG NIET worden opgenomen.

@ForceAuthn

eHerkenning: De waarde MOET “true” zijn tenzij Single Sign-On wordt gebruikt (zie paragraaf 2.5 voor beperkingen).

@IsPassive



Data element

Invulling

@ProtocolBinding

SAML: MAG NIET worden opgenomen omdat AssertionConsumerServiceIndex binnen eHerkenning is voorgeschreven.

@AssertionConsumer ServiceIndex

eHerkenning: Dit attribuut element geeft aan naar welke url de HM het antwoord voor de DV stuurt. Dit index verwijst naar een url in de dienstverlenermetadata. De HM en DV moeten, voor het gebruik van dit veld, indices met urls specificeren. De waarde van AssertionConsumerServiceIndex MOET overeenkomen met een index van de assertionconsumerservice in de metadata van de dienstverlener.

@AssertionConsumerServic eURL

SAML: MAG NIET worden opgenomen omdat AssertionConsumerServiceIndex binnen eHerkenning is voorgeschreven.

@AttributeConsumingServic eHerkenning: MOET een ServiceID (in het korte formaat) bevatten. eIndex Zie paragraaf 9.2.2. @ProviderName

eHerkenning: MAG worden opgenomen, maar MOET worden genegeerd door de eHerkenningsmakelaar12.

Issuer

eHerkenning: MOET de EntityID van de dienstverlener bevatten. Zie paragraaf 9.2.3. De attributen NameQualifier, SPNameQualifier, Format en SPProviderID MOGEN NIET worden opgenomen.

Signature

eHerkenning: MOET de elektronische handtekening van de dienstverlener over het hele bericht bevatten. Zie paragraaf 3.2 voor specifieke eisen.

Extensions eHerkenning: Optioneel element. Indien aanvullende attributen worden uitgevraagd MAG hier één RequestedAttributes element worden opgenomen. In het RequestedAttributes element MOETEN uitsluitend attributen worden opgenomen die zijn opgenomen in de attribuutcatalogus (zie hoofdstuk 7). Deze attributen MOETEN worden opgenomen als Name van een RequestedAttribute. Andere XML attributen MOGEN NIET worden opgenomen. Andere elementen MOGEN NIET worden opgenomen. Een herkenningsmakelaar MAG dit veld negeren, maar MOET het bericht als valide accepteren. Subject

eHerkenning: MAG NIET worden opgenomen

NameIDPolicy


Conditions


12

De eHerkenningsmakelaar gebruikt ook het element ProviderName, maar vult dit op andere wijze.


Data element

Invulling

RequestedAuthnContext

eHerkenning: MOET een attribuut Comparison=”minimum” en een element AuthnContextClassRef met daarin opgenomen het door de dienstverlener vereiste minimale betrouwbaarheidsniveau bevatten. Zie paragraaf 9.2.1.

Scoping


248

5.2

Response (2)

249

Zie paragraaf 11.2 voor een voorbeeld. Data element

Invulling

@ID

SAML: Uniek kenmerk van het bericht.

@InResponseTo

SAML: Uniek kenmerk van het AuthnRequest waarop dit Response bericht het antwoord is.

@Version


@IssueInstant

SAML: Tijd waarop het bericht is aangemaakt.

@Destination

SAML: URL van de dienstverlener waarop het bericht wordt aangeboden. MOET overeenkomen met de metadata van de dienstverlener.

@Consent


Issuer

eHerkenning: MOET de EntityID van de eHerkenningsmakelaar bevatten. Zie paragraaf 9.2.3. De attributen NameQualifier, SPNameQualifier, Format en SPProviderID MOGEN NIET worden opgenomen.

Signature

eHerkenning: MOET de elektronische handtekening van de eHerkenningsmakelaar over het hele bericht bevatten. Zie paragraaf 3.2 voor specifieke eisen.

Extensions


Status

eHerkenning: MOET een element StatusCode bevatten met daarin de status van de authenticatie. In geval van annuleren of een fout MOET dit element worden gevuld met de waarde AuthnFailed. Zie ook de beschrijvingen in hoofdstuk 4. StatusDetail MAG NIET worden opgenomen.

Assertion

eHerkenning: MOET een verklaring over de authenticatie met daarin een verklaring over de bevoegdheid bevatten (zie de volgende paragraaf).


250

5.2.1

Verklaring over authenticatie

Data element

Invulling

Assertion

@Version


@ID

SAML: Unieke referentie naar de assertion

@IssueInstant SAML: Tijd waarop de assertion is aangemaakt Issuer


Signature


Subject

eHerkenning: MOET een NameID element bevatten met daarin het specifiek pseudoniem van de handelende natuurlijk persoon. Zie paragraaf 9.2.4.1. Het NameID element MOET een NameQualifier attribuut hebben, dat is gevuld met het EntityID van het machtigingenregister. Een SubjectConfirmation element dat voldoet aan het Web Browser SSO profile MOET zijn opgenomen. Andere SubjectConfirmation of SubjectConfirmationData elementen MOGEN NIET worden opgenomen.

Conditions

eHerkenning: MOET worden opgenomen. De attributen NotBefore en NotOnOrAfter MOETEN worden gevuld met respectievelijk het tijdstip van uitgifte van de assertion en 120 seconden na de uitgifte van de assertion. Een Audience element in het AudienceRestriction element dat voldoet aan het Web Browser SSO profile MOET zijn opgenomen. Andere Audience elementen MOGEN NIET worden opgenomen. Andere Conditions MOGEN NIET worden opgenomen.

Advice



Data element AuthnStatem ent

Invulling eHerkenning: Het attribuut AuthnInstant MOET het tijdstip van authenticatie bevatten. Het AuthnContext element MOET een AuthnContextClassRef element met daarin het betrouwbaarheidsniveau dat is gebruikt* bevatten. Zie paragraaf 9.2.1 respectievelijk paragraaf 9.1. Het AuthenticatingAuthority element MOET zijn gevuld met het EntityID van de authenticatiedienst die de authenticatie heef uitgevoerd. Andere attributen en elementen MOGEN NIET worden opgenomen. * Het betrouwbaarheidsniveau dat is gebruikt MOET het laagste zijn van de betrouwbaarheidsniveaus van de verklaring over de authenticatie van de authenticatiedienst en de verklaring over de bevoegdheid van het machtigingenregister.

AttributeState eHerkenning: MOET een verklaring over de bevoegdheid van de handelende ment natuurlijk persoon bevatten. (zie de volgende paragraaf). Wanneer aanvullende attributen door de dienstverlener zijn gevraagd en deze attributen door authenticatiedienst en/of machtigingenregister zijn geleverd MOGEN deze hier worden opgenomen. Andere AttributeStatement elementen MOGEN NIET worden opgenomen.

251

5.2.2

Verklaring over bevoegdheid

Data element

Invulling

Onderdeel AttributeSta van tement verklaring over authenticatie

eHerkenning: MOET de attributen EntityConcernedID en ServiceID (ServiceID in het lange formaat) bevatten en MAG de attributen EntityConcernedSubID en OldEntityConcernedSubID bevatten. Gedurende de migratieperiode voor vestigingsnummers van de KvK (zie ook paragraaf 8.1.4) MOETEN in geval van een afbakening van een bevoegdheid naar vestiging zowel EntityConcernedSubID als OldEntityConcernedSubID worden meegegeven. Andere attributen MOGEN NIET worden opgenomen.

252

5.3

253

Wanneer de beschreven berichten over de in paragraaf 2.2.2.2 beschreven alternatieve binding

254

Alternatieve binding

worden uitgewisseld gelden de volgende eisen.


255

5.3.1

256

Voor de implementatie voor de HTTP Redirect binding gelden de volgende eisen:

257

• • •

Het gecomprimeerde en gecodeerde bericht MOET aan het URL toegevoegd worden als een query string parameter en MOET worden aangeduid als SAMLRequest.

262 263

Het bericht MOET worden gecomprimeerd met de DEFLATE methode waarna Base64 encoding MOET worden toegepast.

260 261

Het AuthnRequest bericht is gelijk aan het bericht beschreven in paragraaf 5.1, maar MAG NIET een element bevatten.

258 259

HTTP Redirect binding

•

Als RelayState data wordt meegegeven in het HTTP Redirect bericht moet deze apart

264

geencodeerd aan de URL toegevoegd worden als een query string parameter en MOET

265

deze worden aangeduid als RelaySate. Als er geen RelayState wordt meegegeven MOET de hele parameter ontbreken in de URL.

266 267

•

Over het deel van de URL SAMLRequest=value&RelayState=value MOET een elektronische

268

handtekening worden berekend. Deze elektronische handtekening MOET gegenereerd

269

worden zoals beschreven in paragraaf 3.2. De elektronische handtekening MOET worden

270

opgenomen als een query string parameter. Deze parameter wordt aangeduid als

271

Signature.

272

5.3.2

HTTP Artifact binding

273

Voor de implementatie van de HTTP Artifact binding worden allen eisen gesteld aan de

274

ArtifactResolve en ArtifactResponse berichten.

275

5.3.2.1

ArtifactResolve

Data element

Invulling

@ID

SAML: Uniek kenmerk van het bericht

@Version


@IssueInstant

SAML: Tijd waarop het bericht is aangemaakt

@Destination


@Consent


Issuer

eHerkenning: MOET de EntityID van de dienstverlener bevatten. Zie paragraaf 9.2.3. De attributen NameQualifier, SPNameQualifier, Format en SPProviderID MOGEN NIET worden opgenomen.

Signature

eHerkenning: MOET de elektronische handtekening van de dienstverlener over het hele bericht bevatten. Zie paragraaf 3.2 voor specifieke eisen.


276

Data element

Invulling

Extensions


Artifact

SAML: Bevat het Artifact dat als query parameter is ontvangen.

5.3.2.2

ArtifactResponse

Data element

Invulling

@ID

SAML: Uniek kenmerk van het bericht.

@InResponseTo

SAML: Uniek kenmerk van het AuthnRequest waarop dit Response bericht het antwoord is.

@Version


@IssueInstant

SAML: Tijd waarop het bericht is aangemaakt.

@Destination


@Consent


Issuer


Signature

eHerkenning: MOET de elektronische handtekening van de eHerkenningsmakelaar over het hele bericht bevatten. Zie paragraaf 3.2 voor specifieke eisen.

Extensions


Status

eHerkenning: MOET een element StatusCode bevatten met daarin de status van de authenticatie. In geval van annuleren of een fout MOET dit element worden gevuld met de waarde AuthnFailed. Zie ook de beschrijvingen in hoofdstuk 4. StatusDetail MAG NIET worden opgenomen.

any ##any

eHerkenning: MOET een Response bericht bevatten (zie paragraaf 5.2). Dit bericht MAG NIET een element bevatten.


277

6

Dienstencatalogus

278

In dit hoofdstuk wordt het formaat en de publicatie van de dienstencatalogus beschreven.

279

6.1

280

De dienstencatalogus MOET voldoen aan het volgende formaat:

Formaat

281

•

IssueInstant (Tijdstip waarop de dienstencatalogus is aangemaakt)

282

•

NotOnOrAfter (Tijdstip waarop de dienstencatalogus niet meer geldig is)

283

•

Version (Versie van de dienstencatalogus in het formaat nl:eherkenning::. Bijv. nl:eherkenning:0.8def:1)

284 285

•

dienstverlener, ten behoeve van authenticiteit, integriteit en onweerlegbaarheid).

286 287 288

Signature (Ondertekening door beheerorganisatie, eHerkenningsmakelaar of

•

Per dienstverlener: ◦

IsPublic (attribuut dat aangeeft of de dienstverlener eHerkenning publiekelijk in gebruik heeft)

289 290

◦

ServiceProviderID (Het OIN van de dienstverlener)

291

◦

OrganizationDisplayName (De naam van de dienstverlener zoals deze door deelnemers MOET worden afgebeeld, max 64 tekens). Dit element MAG voor verschillende talen

292

worden opgenomen.

293 294 295

◦

Per dienst: ▪

heeft)

296 297

▪

nummer>

299 ▪

ServiceName (Naam van de dienst, bepaald door de dienstverlener, max 64 tekens) Dit element MAG voor verschillende talen worden opgenomen.

301 302

ServiceID (Een door de dienstverlener toegekend en aangeleverd uniek nummer van 1 tot 64000 in het formaat urn:nl:eherkenning:DV::services:
298 300

IsPublic (attribuut dat aangeeft of de dienst eHerkenning publiekelijk in gebruik

▪

ServiceDescription (Korte omschrijving van dienst, max 1024 tekens, bepaald door

303

dienstverlener. Machtigingenregisters MOGEN deze tekst gebruiken om beheerders

304

te helpen bij het vastleggen van bevoegdheden). Dit element MAG voor verschillende talen worden opgenomen.

305 306 307

▪

ServiceDescriptionURL (Een url van max. 512 tekens waar een uitgebreide omschrijving van dienst is te vinden, bepaald door dienstverlener.


Machtigingenregisters MOGEN deze link opnemen om beheerders te helpen bij het

309 310

vastleggen van machtigingen).Dit element MAG voor verschillende talen worden

311

opgenomen.

312

▪

AuthnContextClassRef (Betrouwbaarheidsniveau dat vereist is voor de dienst, bepaald door dienstverlener)

313 314

Het formaat van de dienstencatalogus is de vorm van een XML Schema opgenomen in hoofdstuk

315

10.

316

6.2

317

De beheerorganisatie publiceert de dienstencatalogus op een vaste locatie.

318

Een deelnemer MOET periodiek op een vooraf door de beheerorganisatie gekozen tijdstip, de

Publicatie

319

dienstencatalogus verwerken. Gegevens over de URL en de periodiciteit staan beschreven in

320

[Operationeel handboek].

321

Een deelnemer ZOU de metadata MOETEN verwerken met een automatisch proces. Een deelnemer

322

MOET in verband met rollback, of andere wijzigingen, dit automatische proces ook op

323

tussentijdse momenten kunnen uitvoeren.


324

7

Attribuutcatalogus

325

Dit hoofdstuk definieert de in eHerkenning maximaal beschikbare aanvullende attributen die

326

kunnen worden opgevraagd. Het betreft hier uitsluitend ongevalideerde attributen. Het leveren

327

van deze attributen is niet verplicht.

328

Per attribuut wordt een naam en formaat gespecificeerd. Ook wordt aangegeven of het attribuut

329

door een authenticatiedienst of machtigingenregister kan worden geleverd.

330

Alle attribuut strings zijn opgemaakt in de Unicode character set in UTF-8, net zoals de rest van

331

het bericht. Het RequestedAttributes heeft de namespace:

332

“urn:nl:eherkenning:1.3a:attributeextension:RequestedAttributes”. Geleverde attributen hebben

333

een attributenaam die begint met "urn:nl:eherkenning:1.3:AdditionalAttribute".

334

Voor de leesbaarheid is dat niet opgenomen in onderstaande tabel.

335

(zie eHerkenning XML schema extensions, hoofdstuk 12). Attribuutnaam

Format

Omschrijving

AD/MR

BusinessAddress

String max 256

Adres van de handelende

MR

natuurlijk persoon, in de

context van de gebruikte bevoegdheid BusinessEmail

String max 256

E-Mailadres van de

handelende natuurlijk

MR

persoon, in de context van de gebruikte bevoegdheid BusinessPhone

String max 128

Telefoonnummer van de handelende natuurlijk

MR

persoon, in de context van de gebruikte bevoegdheid

ActingPersonName PersonalEmail

String max 128

Naam van de handelende

AD

String max 256

E-Mailadres van de

AD

natuurlijk persoon

handelende natuurlijk persoon, geregistreerd bij middelenuitgifte (zou dus privé kunnen zijn)


PersonalPhone

String max 128

Telefoonnummer van de handelende natuurlijk persoon, geregistreerd bij middelenuitgifte (zou dus privé kunnen zijn)

AD

BusinessName

String max 128

Naam van het handelde

MR

bedrijf. Userdefined

String max 256

Een

gebruikersgedefinieerd

MR

attribuut is een tekstveld

dat bij de registratie door degene die opgave doet wordt vastgelegd. BusinessAddressCity

String max 128

Plaatsnaam van de

MR


persoon, in de context van de bevoegdheid. BusinessAddressPostalCo de

String max 128

Postcode van de


MR

persoon, in de context van de bevoegdheid. BusinessAddressHouseN umber

String max 128

Huisnummer van de handelende natuurlijk persoon, in de context van de bevoegdheid.

MR

336

De attributen BusinessAddressCity, BusinessAddressPostalCode en BusinessAddressHouseNumber

337

worden naast het attribuut BusinessAddress redundant toegestaan.

338

De attributen in bovenstaande tabel mogen voor handelende natuurlijk personen waarvan de

339

bevoegdheid beperkt is tot een bepaalde vestiging eveneens per vestiging worden vastgelegd.


340

8

Metadata

341

In het eHerkenning netwerk is het gebruik van SAML metadata tussen deelnemers verplicht voor

342

het beschrijven van de URLs en certificaten die worden gebruikt op de verschillende

343

koppelvlakken. Tussen dienstverleners en eHerkenningsmakelaars is het niet verplicht gebruik te

344

maken van SAML metadata. Wanneer wel gebruik wordt gemaakt van SAML metadata kan gebruik

345

gemaakt worden van het in de volgende paragraaf beschreven niet normatieve formaat.

346

8.1

347

De metadata is een valide SAML bestand, volgens urn:oasis:names:tc:SAML:2.0:metadata met

348

daarin één ondertekend EntityDescriptor element. De ondertekening wordt uitgevoerd conform

Formaat metadata

349

hetgeen is beschreven in hoofdstuk 3.

350

Het element EntityDesciptor bevat het entityID en bevat geen andere SAML attributen. Het entityID

351

heeft de vorm urn:nl:eherkenning:ROL:OIN:INDEX, waarbij ROL één van DV of HM is afhankelijk

352

van de rol, OIN het OIN is van de dienstverlener of eHerkenningsmakelaar, en INDEX een

353

zelfgekozen index is van vier cijfers.

354

Voorbeeld:

355

356

<md:EntityDescriptor

357

ID="[reference for dsig]"

358

xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"

359

xmlns:attr="urn:oasis:names:tc:SAML:metadata:attribute"

360

xmlns:ds="http://www.w3.org/2000/09/xmldsig#"

361

entityID="urn:nl:eherkenning:HM:9999990000010000:0001" > ...

362 363

...

364

365

In de EntityDescriptor worden één of meerdere elementen van het type ContactPerson opgenomen

366

waarin naam, emailadres, en telefoonnummer staan beschreven van personen met wie, in geval

367

van problemen, contact kan worden opgenomen.

368

In de metadata zijn gegevens opgenomen over de eigen organisatie, door het opnemen van één

369

element van het type Organization, waarin naam (OrganizationName), de leesbare naam voor

370

gebruikers (OrganizationDisplayName), en website (OrganizationURL) staan beschreven.

371

Een rol kan met meerdere systemen worden vervult. Voor ieder systeem afzonderlijk wordt dan Afsprakenstelsel eHerkenning - Koppelvlak DV-HM | Datum:28 april 2012 | Versie: 1.4 | 27/43

372

metadata aangeleverd. De metadata bevat dan een verschillend EntityID, waar het element

373

Organization hetzelfde is.

374

Wanneer een systeem verschillende versies van het afsprakenstelsel ondersteunt moet voor elke

375

versie afzonderlijk metadata worden aangeleverd.

376

Een eHerkenningsmakelaar neemt één IDPSSODescriptor element op met daarin één

377

SingleSignOnService element en geen andere elementen.

378

Voorbeeld:

379

...

380

<md:IDPSSODescriptor WantAuthnRequestsSigned="true"

381

protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" >

<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"

382 383

Location="https://...."/>

384

385

...

386

Een dienstverlener neemt één SPSSODescriptor op en geen andere elementen.

387

Voorbeeld eHerkenningsmakelaar:

388

...

389

<md:SPSSODescriptor AuthnRequestsSigned="true"

390 391 392

WantAssertionsSigned ="true"

protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

...

<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"

393 394

Location="https://..." index="1"/>

395

396

...

397

Een IDPSSODescriptor bevat als attribuut WantAuthnRequestsSigned=true en bevat geen andere

398

optionele attributen. Een SPSSODescriptor element bevat als attribuut AuthnRequestsSigned=true

399

en WantAssertionsSigned=true en geen andere optionele attributen.

400

Een IDPSSODesriptor of SPSSODescriptor bevat één of meerdere KeyDescriptor elementen met het

401

attribuut use="signing". Ieder KeyDescriptor element bevat een KeyName én een geldig G2

402

PKIoverheid certificaat, waarmee de SAML berichten van de deelnemer kunnen worden

403

geauthenticeerd. Nota bene: Dienstverlener en eHerkenningsmakelaar moeten alle genoemde

404

KeyDescriptors verwerken. In de handtekeningen in de protocolberichten wordt door middel van

405

de KeyName aangeduid welk certificaat uit de metadata is gebruikt voor de ondertekening.

406

Voorbeeld:


407

...

408

<md:KeyDescriptor use="signing">

409

410 411

2fd4e1c6 7a2d28fc ed849ee1 bb76e739 1b93eb12

412

413 414 415

...

416

417

418 419

420

...


421

9

Data-elementen

422

Dit hoofdstuk beschrijft alle voor eHerkenning gedefinieerde data-elementen. Gebruikte SAML

423

elementen die zuiver volgens de SAML standaard worden gebruikt zijn hier niet opgenomen.

424

9.1

425

Binnen eHerkenning wordt het OIN formaat gebruikt om dienstafnemers, vestigingen, deelnemers

OIN formaat

426

en dienstverleners aan te duiden. Het OIN formaat is gedefinieerd binnen DigiKoppeling. Een OIN

427

bestaat uit de volgende geconcateneerde elementen:

428

•

Een prefix van 8 cijfers die het register aanduidt waar het nummer is gedefinieerd

429

•

Een nummer waarvan de invulling afhangt van het register

430

Binnen eHerkenning worden FI-nummers, KvK nummers, vestigingsnummers en nummers uit de

431

DigiKopeling registry gebruikt. Nummers uit buitenlandse handelsregisters of vergelijkbare

432

openbare registers kunnen worden toegevoegd nadat daarvoor een specifieke prefix is

433

uitgegeven. De betreffende nummers uit het betreffende nummer worden aangeduid met

434

“toegelaten buitenlands nummer”.Hieronder wordt de exacte definitie van elk nummer

435

beschreven.

436

9.1.1

437

Het FI-nummer heeft als prefix 00000001 of 00000002. Het nummer bestaat uit het 9-cijferige

438

nummer met een suffix van 3 cijfers. Voor prefix 00000001 is deze suffix altijd 000.

FI-nummer

439

Voorbeeld: 00000001123456789000 of 00000002123456789001

440

9.1.2

441

Het KvK nummer heeft als prefix 00000003.

442

Het nummer bestaat uit het 8-cijferige KvK nummer met een suffix van 0000, bijvoorbeeld:

443

00000003123456780000

444

9.1.3

445

Het nieuwe vestigingsnummer heeft als prefix 000000? (Is nog ntb in overleg met Logius). Het

KvK nummer

Vestigingsnummer (nieuwe formaat)

446

nummer bestaat uit het 12-cijferige vestigingsnummer, bijvoorbeeld:

447

0000000?123456789012


448

9.1.4

Vestigingsnummer (oude formaat)

449

Het oude vestigingsnummer heeft als prefix 00000003.

450

Het nummer bestaat uit het 8-cijferige KvK nummer en het 4-cijferige vestigingsnummer,

451

bijvoorbeeld:

452

00000003123456780008

453

N.B. Tot 31 december 2013 zal de KvK voor alle vestigingen (bestaande en nieuw te registreren)

454

een oud en een nieuw vestigingsnummer registreren.

455

9.1.5

456

Dit nummer wordt door Logius uitgegeven aan dienstverleners die geen (eigen) KvK nummer

DigiKoppeling registry

457

hebben.

458

Het nummer uit de DigiKoppeling registry heeft als prefix 00000004.

459

Het nummer bestaat uit een 9-cijferig nummer gevolgd door 000, bijvoorbeeld:

460

00000004123456789000

461

9.1.6

462

Voor het gebruik van eHerkenning door buitenlandse dienstafnemers uit andere EU lidstaten

Buitenlandse registers

463

kunnen specifieke prefixen worden vastgesteld in samenwerking met Logius en het Nederlandse

464

dienstenloket (Antwoord voor Bedrijven). Daarbij wordt per register van betreffend land een prefix

465

uitgegeven. Indien van toepassing wordt er zowel een prefix voor het bedrijfsniveau

466

(onderneming en rechtspersoon) als een prefix voor het vestigingsniveau uitgegeven. Per land

467

moet op de website van eHerkenning worden gecommuniceerd dat dienstafnemers van het

468

betreffende land hiervan gebruik kunnen maken, onder verwijzing naar het Nederlandse

469

dienstenloket en de specifieke voorschriften van het betreffende land.

470

Daarbij geldt de regel dat indien er een KvK nummer is uitgegeven aan de betreffende

471

dienstafnemer dat altijd dat nummer gebruikt moet worden. Dat wil zeggen dat in het

472

Nederlandse handelsregister ingeschreven dienstafnemers en vestigingen van buitenlandse

473

dienstafnemers niet het nummer waarin zij in een buitenlands register zijn ingeschreven mogen

474

gebruiken binnen eHerkenning. Indien enig onderdeel van de dienstafnemer in het Nederlandse

475

handelsregister is geregistreerd dan moet het KvK nummer gebruikt worden.

476

9.2

477

Binnen eHerkenning worden de volgende identificerende kenmerken gedefinieerd.

Identificerende kenmerken


478

9.2.1

479

Om de betrouwbaarheidsniveaus van eHerkenning in de berichten te onderscheiden wordt

480

onderstaande subset van de in de SAML 2.0 specificaties voor het AuthnContextClassRef element

481

Betrouwbaarheidsniveau

gebruikte waarden toegestaan. Andere waarden MOGEN NIET worden gebruikt. eHerkenning niveau

SAML2 AuthnContextClassRef element

1

urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

213

urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorUnregistered

3

urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorContract

4

urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI

482

Zie ook document [eHerkenning - Betrouwbaarheidsniveaus].

483

9.2.2

484

Binnen eHerkenning worden alle diensten aangeduid met een binnen de context van de

ServiceID

485

dienstverlener uniek nummer, de ServiceID. Elk ServiceID is in de dienstencatalogus opgenomen

486

als onderdeel van een urn van het formaat

487

urn:nl:eherkenning:DV::services:<ServiceID>

488

waarbij staat voor het OIN van de dienstverlener die de dienst verleent. Door middel van

489

de urn worden diensten uniek binnen eHerkenning gedefinieerd.

490

Geregistreerde diensten MOETEN een ServiceID van 1 of hoger hebben. Een loket- of portalfunctie

491

wordt in berichten aangeduid met het gereserveerde ServiceID met waarde '0'. Deze wordt niet

492

opgenomen in de dienstencatalogus.

493

De ServiceID wordt in berichten in twee formaten gebruikt: 1. Het korte formaat. Hier wordt alleen de ServiceID opgenomen.

494

2. Het lange formaat. Hier wordt de volledige urn opgenomen.

495

496

9.2.3

497

Binnen eHerkenning worden alle systemen van deelnemers en dienstverleners aangeduid met een 13

EntityID

Niveau werd tijdens de proefimplementaties aangeduid met de benaming “niveau NL”. Het oude niveau 2 is komen te vervallen.


498

EntityID die is opgenomen in de metadata. De EntityID is van het formaat

499

urn:nl:eherkenning:::entities:

500

waarbij de waarden DV, HM, AD of MR kan hebben, staat voor het het KvK nummer

501

of DigiKoppeling nummer van de deelnemer of het FI-nummer,KvK nummer of DigiKoppeling

502

nummer dienstverlener. De is een vrij door deelnemer of dienstverlener te kiezen

503

nummer van 0 t/m 8999 om verschillende endpoints mee te definiëren. Nummers van 9000 t/m

504

9999 zijn gereserveerd voor testsystemen.

505

9.2.4

506

Binnen eHerkenning wordt een handelende natuurlijk persoon op twee verschillende manieren

507 508 509

aangeduid:

1. binnen het netwerk met een intern pseudoniem door de authenticatiedienst; en 2. binnen en buiten het netwerk met een specifiek pseudoniem door het machtigingenregister

510 511

Pseudoniemen

Om de bescherming van de privacy van de handelende natuurlijk persoon te waarborgen wordt

512

aan een dienstverlener uitsluitend een specifiek pseudoniem verstrekt.

513

Het intern pseudoniem is niet relevant voor dit koppelvlak en wordt verder niet beschreven.

514

9.2.4.1

515

Het specifiek pseudoniem wordt door het machtigingenregister eenmalig bepaald en vervolgens

Specifiek pseudoniem

516

aan de handelende natuurlijk persoon gekoppeld. Het specifiek pseudoniem MOET uniek zijn

517

binnen eHerkenning en voor elke verschillende combinatie van dienstverlener, handelende

518

natuurlijk persoon en handelende dienstafnemer MOET een verschillend specifiek pseudoniem

519

worden geregistreerd en gebruikt. Het machtigingenregister MOET een pseudoniem t.b.v. van een

520

dienstverlener genereren wanneer voor een handelende natuurlijk persoon één of meer

521

machtigingen voor diensten van die dienstverlener zijn geregistreerd. Zolang de combinatie van

522

de handelende natuurlijk persoon en de handelende dienstafnemer ongewijzigd blijft bestaat er

523

geen verplichting nieuwe pseudoniemen te bepalen. Op verzoek van de wettelijke

524

vertegenwoordiger, beheerder en/of de handelende natuurlijk persoon MOGEN echter altijd

525

nieuwe pseudoniemen worden gegenereerd. Een eenmaal gebruikt specifiek pseudoniem MAG

526

NIET worden hergebruikt. Portabiliteit van specifiek pseudoniemen is mogelijk doordat eenmaal

527

gegenereerde pseudoniemen voor de betreffende handelende natuurlijk persoon in andere

528

machtigingenregisters MOGEN worden opgenomen.

529

Het formaat van het specifiek pseudoniem MOET hexadecimale waarde van 32 byte gevolgd door


530

een @ en een hexadecimale waarde van 16 byte. Bijv.

531

ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890@ABCDEF1234

532

567890ABCDEF1234567890

533

De waarde van 32 byte MOET een random waarde zijn. Dit kan worden bereikt een SHA256 hash

534

over de volgende elementen (in deze volgorde en gescheiden door een scheidingsteken) te

535

berekenen:

Het OIN van de dienstverlener

536

•

537

•

Het OIN van de handelende dienstafnemer

538

•

Een in de context van de handelende dienstafnemer uniek (doch niet perse exclusief)

539

identificerend kenmerk van de handelende natuurlijk persoon. Dit kenmerk MAG door de

540

beheerder of door het machtigingenregister bepaald worden, maar MAG ook het interne pseudoniem zijn.

541 542 543

•

Een 16 byte random nummer.

De waarde van 16 byte MOET een MD5 hash over het OIN van de handelende dienstafnemer zijn.

544

N.B. Er kunnen nog andere formaten in omloop zijn. Gebruikers van het specifiek pseudoniem

545

wordt dan ook afgeraden (delen van) het pseudoniem te gebruiken voor andere doeleinden dan

546

het identificeren van de handelende natuurlijk persoon.

547

9.3

548

Deze paragraaf beschrijft de data-elementen die als SAML Attribute element in berichten

SAML Attributen

549

voorkomen.

550

De voor eHerkenning specifieke attributen worden aangeduid met een urn. Deze urn bevat het

551

versienummer van het afsprakenstelsel waarin (die versie) van het betreffende attribuut voor het

552

eerst is opgenomen.

553

9.3.1

EntityConcernedID

Omschrijving

Een SAML Attribute element met daarin het OIN van het KvK nummer of toegelaten buitenlands nummer van de handelende dienstafnemer dat door de handelende natuurlijk persoon vertegenwoordigd wordt.

Name

urn:nl:eherkenning:1.0:EntityConcernedID

Type

http://www.w3.org/2001/XMLSchema#string

AttributeValue

Zie paragraaf 9.1.

Opmerkingen

N.B. door het gebruik van het OIN formaat wordt het KvK nummer gevolgd door 0000. Hiermee wordt nadrukkelijk geen afbakening van de bevoegdheid naar een vestiging geïmpliceerd. Het OIN is


bedoeld uitsluitend het KvK nummer aan te duiden.

554

9.3.2

EntityConcernedSubID 1.2

Omschrijving

Een optioneel SAML Attribute element met daarin het OIN van het vestigingsnummer in het nieuwe formaat (zie paragraaf 9.1.3) of toegelaten buitenlands vestigingsnummer (zie paragraaf 9.1.6) waartoe de bevoegdheid van de handelende natuurlijk persoon is afgebakend.

Name

urn:nl:eherkenning:1.2:EntityConcernedSubID

Type


AttributeValue

Zie paragraaf 9.1.3 en 9.1.6

Opmerkingen

555

556

9.3.3

OldEntityConcernedSubID 1.2

Omschrijving

Een optioneel SAML Attribute element met daarin het OIN van het vestigingsnummer in het oude formaat (zie paragraaf 9.1.4) waartoe de bevoegdheid van de handelende natuurlijk persoon is afgebakend.

Name

urn:nl:eherkenning:1.2:OldEntityConcernedSubID

Type


AttributeValue

Zie paragraaf 9.1.4

Opmerkingen

N.B. De laatste vier cijfers duiden altijd expliciet een vestiging aan.

9.3.4

ServiceID

Omschrijving

Een SAML Attribute element met daarin de ServiceID van de dienst waarvoor de bevoegdheid geldt. Zie paragraaf 9.2.2.

Name

urn:nl:eherkenning:1.0:ServiceID

Type


AttributeValue

Zie paragraaf 9.2.2. De waarde MOET overeenkomen met de waarde van @AttributeConsumingServiceID uit het AuthnRequest. Zie paragraaf 5.1.

557

9.4

URL of POST variabele: EherkenningPreferredLanguage

Omschrijving

Taalvoorkeur van handelende natuurlijk persoon

Naam

EherkenningPreferredLanguage


Formaat

Volgens ISO 639-1:2002


558

10

Bijlage XML Schema dienstencatalogus

559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:eh="urn:nl:eherkenning:1.0" targetNamespace="urn:nl:eherkenning:1.0" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:import namespace="http://www.w3.org/2000/09/xmldsig#" schemaLocation="http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd"/> <xs:import namespace="urn:oasis:names:tc:SAML:2.0:assertion" schemaLocation="saml-schema-assertion2.0.xsd"/> <xs:import namespace="urn:oasis:names:tc:SAML:2.0:metadata" schemaLocation="saml-schema-metadata2.0.xsd"/> <xs:element name="Service"> <xs:complexType> <xs:sequence> <xs:element ref="eh:ServiceID"/> <xs:element ref="eh:ServiceName" maxOccurs="unbounded"/> <xs:element ref="eh:ServiceDescription" maxOccurs="unbounded"/> <xs:element ref="eh:ServiceDescriptionURL" minOccurs="0" maxOccurs="unbounded"/> <xs:element ref="saml2:AuthnContextClassRef"/> <xs:attribute ref="eh:IsPublic" use="required"/> <xs:element name="ServiceCatalogue"> <xs:complexType> <xs:sequence> <xs:element ref="ds:Signature"/> <xs:element ref="eh:ServiceProvider" maxOccurs="unbounded"/> <xs:attribute ref="eh:IssueInstant" use="required"/> <xs:attribute ref="eh:NotOnOrAfter" use="required"/> <xs:attribute ref="eh:Version" use="required"/> <xs:attribute name="ID" type="xs:string"/> <xs:element name="ServiceDescription"> <xs:complexType> <xs:simpleContent> <xs:restriction base="md:localizedNameType"> <xs:maxLength value="512"/> <xs:element name="ServiceDescriptionURL"> Afsprakenstelsel eHerkenning - Koppelvlak DV-HM | Datum:28 april 2012 | Versie: 1.4 | 37/43

606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649

<xs:complexType> <xs:simpleContent> <xs:restriction base="md:localizedURIType"> <xs:maxLength value="512"/> <xs:element name="ServiceID" type="xs:anyURI"/> <xs:element name="ServiceName"> <xs:complexType> <xs:simpleContent> <xs:restriction base="md:localizedNameType"> <xs:maxLength value="64"/> <xs:element name="ServiceProvider"> <xs:complexType> <xs:sequence> <xs:element ref="eh:ServiceProviderID"/> <xs:element ref="eh:OrganizationDisplayName" maxOccurs="unbounded"/> <xs:element ref="eh:Service" maxOccurs="unbounded"/> <xs:attribute ref="eh:IsPublic" use="required"/> <xs:element name="ServiceProviderID" type="xs:anyURI"/> <xs:element name="OrganizationDisplayName"> <xs:complexType> <xs:simpleContent> <xs:restriction base="md:localizedNameType"> <xs:maxLength value="64"/> <xs:attribute name="IssueInstant" type="xs:dateTime"/> <xs:attribute name="IsPublic" type="xs:boolean"/> <xs:attribute name="NotOnOrAfter" type="xs:dateTime"/> <xs:attribute name="Version" type="xs:anyURI"/>


650

11

Bijlage voorbeeld berichten

651 652

In deze bijlage worden twee voorbeeldberichten gegeven. Er zijn geen voorbeeldwaarden voor elementen en attributen ingevuld.

653

11.1

654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ForceAuthn="true" Destination=" " AssertionConsumerServiceIndex=" " AttributeConsumingServiceIndex="2" ID=" " IssueInstant=" " Version="2.0" ProviderName=" "> <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"> <samlp:Extensions> <ehsamlp:RequestedAttributes> <md:RequestedAttribute Name="urn:nl:eherkenning1.3:AdditionalAttribute:ActingPersonName"/> <md:RequestedAttribute Name="urn:nl:eherkenning1.3:AdditionalAttribute:PersonalEmail"/> <md:RequestedAttribute Name="urn:nl:eherkenning1.3:AdditionalAttribute:PersonalPhone"/> <samlp:RequestedAuthnContext Comparison="minimum"> <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">

AuthnRequest



695

11.2

Response

696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID=" " InResponseTo=" " Version="2.0" Destination=" " IssueInstant=" "> <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"> <samlp:Status> <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"> <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Version="2.0" ID=" " IssueInstant=" "> <saml:Issuer> <saml:Subject> <saml:NameID> <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <saml:SubjectConfirmationData Recipient=" " NotOnOrAfter=" "> <saml:Conditions NotBefore=" " NotOnOrAfter=" "> <saml:AudienceRestriction> <saml:Audience> Afsprakenstelsel eHerkenning - Koppelvlak DV-HM | Datum:28 april 2012 | Versie: 1.4 | 41/43

743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776

<saml:AuthnStatement AuthnInstant=" "> <saml:AuthnContext> <saml:AuthnContextClassRef> <saml:AuthenticatingAuthority> <saml:AttributeStatement> <saml:Attribute Name="urn:nl:eherkenning:1.0:ServiceID"> <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"> <saml:Attribute Name="urn:nl:eherkenning:1.0:EntityConcernedID"> <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"> <saml:Attribute Name="urn:nl:eherkenning1.3:AdditionalAttribute:ActingPersonName"> <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"> <saml:Attribute Name="urn:nl:eherkenning1.3:AdditionalAttribute:BusinessName"> <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">


777

12

eHerkenning XML Schema extensions

778

12.1

XML schema attribute extension

779 780 781 782 783 784 785 786 787 788 789 790 791 792

<xs:schema xmlns:ehsamlp="urn:nl:eherkenning:1.3a:attributeextension" targetNamespace="urn:nl:eherkenning:1.3a:attributeextension" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="RequestedAttributes"> <xs:complexType> <xs:sequence> <xs:element ref="md:RequestedAttribute" maxOccurs="unbounded"/>


Afsprakenstelsel eherkenning. Koppelvlak DV-HM. Versie 1.4

Recommend Documents