Rapport
aan
van
Aan te sluiten overheidspartij
Kamer van Koophandel Nederland
datum
7 januari 2013 kenmerk
Onderwerp
Technische Aansluitvoorwaarden KvK Web services voor overheidspartijen 1 Versiebeheer
Versiebeheer Versienummer
Datum
Auteur
Wijzigingen
0.1
20-01-2012
0.2
20-03-2012
Erwin Embsen en Marco Fränkel Marco Fränkel
1.0
30-05-2012
Programma HRIP
Eerste versie, gebaseerd op document Technisch Koppelvlak KVK Web services op internet Aanpassingen n.a.v. opmerkingen Matthieu van Bommel, Chiel Drost, Wilko de Vlieger Documentbeheer Productmanagement
1.1
11-07-2012
Marco Fränkel
Bijlages II en III toegevoegd.
1.2
21-09-2012
Marco Fränkel
Toevoeging opmerking response bericht aan §4.5
1.3
15-10-2012
Marco Fränkel
Toevoeging bijlage IV, aanpassing gebruikt WUS profiel
1.4
09-11-2012
Marco Fränkel
1.5
13-11-2012
Marco Fränkel
1.6
22-11-2012
Marco Fränkel
Diverse kleine aanpassingen, aanpassing voorbeeldbericht bevragingen Herstructurering bijlages ter voorbereiding op splitsing WUS/ebMS Aanpassing Diginetwerk/Internet
1.7
30-11-2012
Marco Fränkel
Kleine aanpassingen in §5.1
1.8
19-12-2012
Anne Schrijer
Aanpassing in §5.1.4
1.9
07-01-2012
Marco Fränkel
Aanpassing in §5.1.2 (voetnoot)
Pagina 1 van 7
Kamer van Koophandel Nederland
Inhoudsopgave 1
Versiebeheer ................................................................................................................................................ 1
2
Voorwoord .................................................................................................................................................... 3
3
Inleiding ........................................................................................................................................................ 3
3.1 3.2
Achtergrond .................................................................................................................................................. 3 Waarborgen kwaliteit .................................................................................................................................... 3
4
Techniek ....................................................................................................................................................... 3
4.1 4.2 4.3 4.4 4.5 4.6
Een netwerkaansluiting op Diginetwerk/Internet........................................................................................... 3 Een netwerkverbinding met het doelsysteem bij KVK NL ............................................................................. 3 Postbussen bij KVK NL................................................................................................................................. 4 Beveiliging .................................................................................................................................................... 4 Correcte berichten communiceren met KVK NL ........................................................................................... 4 Een werkende web service bij KVK NL......................................................................................................... 4
5
Bijlage I: KvK-WUS....................................................................................................................................... 5
5.1
Toepassing koppelvlakstandaard ................................................................................................................. 5 5.1.1 SOAP........................................................................................................................................... 5 5.1.2 WS-Addressing............................................................................................................................ 5 5.1.3 WS-Security................................................................................................................................. 5 5.1.4 SSL.............................................................................................................................................. 5 Testen aansluiten bevragingen..................................................................................................................... 6 5.2.1 PING test ..................................................................................................................................... 6 5.2.2 HelloWorld test ............................................................................................................................ 6 Template berichten bij bevragingen.............................................................................................................. 6 Verschillen koppelvlakstandaarden KvK-WUS en Digikoppeling-WUS ........................................................ 7 5.4.1 Standaarden ................................................................................................................................ 7 5.4.2 Technisch contract....................................................................................................................... 7 5.4.3 Adressering.................................................................................................................................. 7 5.4.4 Binaire data.................................................................................................................................. 7 5.4.5 Point-to-point beveiliging.............................................................................................................. 7 5.4.6 End-to-end beveiliging ................................................................................................................. 7 5.4.7 Naamgeving................................................................................................................................. 7 5.4.8 Foutafhandeling ........................................................................................................................... 7
5.2
5.3 5.4
Pagina 2 van 7
Kamer van Koophandel Nederland
2 Voorwoord In dit document worden de web service koppelvlakken tussen overheidspartijen en de Kamer van Koophandel Nederland, hierna KVK NL genoemd, beschreven. Hierbij komt aan de orde hoe de geautomatiseerde communicatie tussen overheidspartijen en de KVK NL moet plaatsvinden, en hoe de berichten die gecommuniceerd worden met de Kamer van Koophandel Nederland vorm moet worden gegeven. Bij het beschrijven van de toegepaste koppelvlakstandaarden wordt verwezen naar de volgende Logius documenten: Koppelvlakstandaard WUS voor Digikoppeling 2.0 Koppelvlakstandaard ebMS voor Digikoppeling 2.0 Deze documenten zijn te vinden op http://www.logius.nl/producten/gegevensuitwisseling/digikoppeling/documentatie/koppelvlakken.
3 Inleiding 3.1 Achtergrond KVK NL biedt thans diverse diensten aan externe afnemers. Daartoe behoren ook ICT diensten die in de vorm van web services worden aangeboden. Via Diginetwerk/Internet biedt KVK NL web services aan voor overheidspartijen. Het gaat hierbij om directe communicatie, waarbij systemen van overheids instellingen direct verbinding maken met de doelsystemen bij KVK NL. 3.2 Waarborgen kwaliteit Om ervoor te zorgen dat u als overheids-instelling de juiste gegevens ontvangt op basis van de web servicesbevragingen die u uitvoert, zijn de volgende maatregelen genomen: -
Het berichtenverkeer moet voldoen aan de eisen zoals in dit document zijn voorgeschreven. Autorisatie van u als klant gebeurt op basis van de beveiligingsaspecten zoals voorgeschreven in de koppelvlakstandaarden ebMS en WUS (zie boven). De gegevens die worden gecommuniceerd met KVK NL moeten voldoen aan de eisen zoals gesteld in deze koppelvlakbeschrijving.
4 Techniek Om een web service koppeling met KVK NL te kunnen maken is het volgende nodig: -
Een netwerkaansluiting + routering op Diginetwerk/Internet. Een bronsysteem dat een netwerkverbinding kan maken met het doelsysteem bij KVK NL. Een postbus bij KVK NL waarop de beoogde web service bereikbaar is. Een bronsysteem dat technisch correcte berichten communiceert met KVK NL. Een werkende web service bij KVK NL.
4.1 Een netwerkaansluiting op Diginetwerk/Internet Een aansluiting op Diginetwerk/Internet is de eerste vereiste om de KVK NL web services voor overheidspartijen te kunnen benaderen. Raadpleeg uw netwerkleverancier voor een aansluiting. Het moet mogelijk zijn om een HTTPS verbinding naar buiten te maken. 4.2 Een netwerkverbinding met het doelsysteem bij KVK NL De web services die KVK NL aanbiedt zijn uitsluitend te benaderen op basis van beveiligde HTTP verbindingen.
Pagina 3 van 7
Kamer van Koophandel Nederland
N.b.: indien u van Diginetwerk gebruik maakt moet uw contactpersoon bij KVK NL weten vanaf welk IP adres u onze web service benadert. Uw lokale netwerkbeheerder kan u deze informatie geven. Dit IP adres wordt op de firewall van KVK NL bekend gemaakt zodat netwerkverbindingen vanaf dit adres worden toegelaten tot KVK NL. Deze procedure geldt zowel voor productie als acceptatie-omgevingen. 4.3 Postbussen bij KVK NL KVK biedt op dit moment een viertal externe postbussen aan: -
Een two-way SSL beveiligde verbinding, specifiek bedoeld voor bevragingen via Diginetwerk (o.b.v. de koppelvlakstandaard WUS, profiel Digikoppeling 2W-be-S) Een two-way SSL beveiligde verbinding, specifiek bedoeld voor leveringen via Diginetwerk (o.b.v. de koppelvlakstandaard ebMS, profiel osb-rm) Een two-way SSL beveiligde verbinding, specifiek bedoeld voor bevragingen via Internet (o.b.v. de koppelvlakstandaard WUS, profiel Digikoppeling 2W-be-S) Een two-way SSL beveiligde verbinding, specifiek bedoeld voor leveringen via Interner (o.b.v. de koppelvlakstandaard ebMS, profiel osb-rm)
Let op! Op deze postbussen zijn geen WSDL’s opvraagbaar. Een overzicht van de postbussen en de daarop beschikbare services en bijbehorende service description documenten (WSDL's en XSD's) is op te vragen bij KVK NL. 4.4 Beveiliging Beveiliging vindt plaats op 3 niveaus: transport-niveau (SSL certificaten, zie §5.1.4) bericht-niveau (message headers, zie §5.1.3) applicatie-niveau (message payload, buiten scope van dit document) 4.5 Correcte berichten communiceren met KVK NL De web services bij KVK NL maken bij bevragingen gebruik van het SOAP protocol. Binnen het SOAP protocol wordt gebruik gemaakt van WS-I standaarden WS-Addressing en WS-Security. WS-Addressing wordt gebruikt om de berichten bij de juiste doelsystemen af te leveren binnen het KVK landschap, en WS-Security wordt gebruikt voor message-level security. Een gedetailleerde uitwerking van de toepassing van deze technologieën is te vinden in bijlage I. N.b.: de response SOAP berichten zullen ook WS-Addressing headers bevatten. 4.6 Een werkende web service bij KVK NL KVK NL zorgt voor werkende web services in alle omgevingen waarop klanten aansluiten. Voor alle omgevingen gelden algemene SLA’s die door KVK NL worden opgesteld. N.b.: voor test-doeleinden is een HelloWorld Web service beschikbaar. Zie §5.1.2 voor de gewenste adresseringgegevens.
Pagina 4 van 7
Kamer van Koophandel Nederland
5 Bijlage I: KvK-WUS
5.1 Toepassing koppelvlakstandaard Voor het gebruik van zaken als SOAP en de WS-technologieën blijven we zo dicht mogelijk bij de door Logius 1 voorgeschreven koppelvlakstandaard WUS . 5.1.1 SOAP Aangeleverde berichten moeten SOAP 1.1 compliant te zijn (zie http://www.w3.org/TR/2000/NOTE-SOAP20000508/). 5.1.2 WS-Addressing Voor routering gebruiken we WS-Addressing 1.0 versie 200508 (zie http://www.w3.org/TR/ws-addr-soap/). -
Destination (wsa:To) bevat een servicenaam zoals die bij KvK bekend is. Action (wsa:Action) bevat een logische, 'leesbare' naam van de uit te voeren actie. Message Id (wsa:MessageID) bevat een unieke, door de afnemer gezette identifier.
Bijvoorbeeld: wsa:To=”http://es.kvk.nl/KVK-HelloWorld/2012/01”, wsa:Action=”http://es.kvk.nl/print” 5.1.3 WS-Security De standaard WS-Security versie 2004/01 wordt gebruikt voor message-level security, zie http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf. Binnen het WS-Security framework maken we gebruik van het Web Services Security 3 X.509 Certificate Token Profile (zie http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0.pdf). N.b.: de gebruikte certificaten dienen te voldoen aan de eisen zoals gesteld in de beschrijvingen van de koppelvlakstandaarden. 5.1.4 SSL Zoals in §4.3 getoond zijn beide postbussen via HTTPS te benaderen. KVK NL beveiligd deze verbindingen met digitale certificaten uitgegeven door PKIoverheid. Om de verbinding tot stand te kunnen brengen moeten deze certificaten door uw organisatie vertrouwd worden. Daarnaast is het vereist dat de klant diens eigen, eveneens door PKIoverheid uitgegeven, certificaat afgeeft bij KVK NL.
1
Voor StUF bevragingen geldt dat er geen afwijkingen zullen zijn.
Pagina 5 van 7
Kamer van Koophandel Nederland
5.2 Testen aansluiten bevragingen Voordat er gebruik gemaakt mag worden van de daadwerkelijke web services, moeten een aantal testen met succes zijn doorlopen, zoals beschreven in het Aansluitplan overheidsafnemer. Voordat de testen kunnen worden uitgevoerd moet contact worden opgenomen met de toegewezen Functioneel Applicatie Beheerder. 5.2.1 PING test Tijdens de 'ping test' (connectiviteits-test) wordt er gekeken of de lijnverbinding operationeel is Bij het uitvoeren van de test moet een ping bericht op TCP/IP niveau door de netwerkbeheerder van de afnemer worden verstuurd. 5.2.2 HelloWorld test Tijdens de HelloWorld test wordt gevalideerd of de de SSL verbinding werkt, en of de juiste (technische) SOAP enveloppe wordt gebruikt. Er wordt gecontroleerd of de juiste WS-* versies worden toegepast, en of de opgegeven gebruikersgegevens geldig zijn. Bij het uitvoeren van de test moet een vooraf gedefinieerd bericht naar de externe postbus worden gestuurd. Een template voor dit bericht is te vinden in bijlage III. De aansluitinformatie is te vinden in het document Catalogus KVK web services Overheid. 5.3 Template berichten bij bevragingen Alle berichten die via de externe postbus voor bevragingen binnen komen, moeten voldoen aan onderstaande template. <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecuritysecext-1.0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Header> <wsse:Security xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsse:BinarySecurityToken EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security1.0#Base64Binary" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509PKIPathv1" wsu:Id="[wsuID]">[BinarySecurityToken]
<ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="soapenv wsa wsnt wsse xsi"/> <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="wsa wsnt wsse xsi"/> [DigestValue] [SignatureValue] <wsse:SecurityTokenReference xmlns:wsse11="http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd" wsse11:TokenType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509PKIPathv1" wsu:Id="[wsuID2]"> <wsse:Reference URI="[ReferenceURI]" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wssx509-token-profile-1.0#X509PKIPathv1"/> <wsa:To>[destination] <wsa:Action>[action] <wsa:MessageID>[messageID] <soapenv:Body>
Pagina 6 van 7
Kamer van Koophandel Nederland
5.4 Verschillen koppelvlakstandaarden KvK-WUS en Digikoppeling-WUS Dit hoofdstuk beschrijft op hoog niveau de belangrijkste verschillen tussen de koppelvlakstandaarden WUS voor Digikoppeling 2.0 (hierna genoemd DK-WUS) en WUS zoals gevoerd door KvK NL bij het aansluiten van overheidspartijen (hierna genoemd KvK-WUS). Onderstaand plaatje toont aan op welke onderwerpen de koppelvlakstandaard KvK-WUS afwijkt van de koppelvlakstandaard DK-WUS. Groen betekent geen verschil, oranje een klein verschil, en rood een groot verschil.
5.4.1 Standaarden Binnen KvK-WUS wordt voor SOAP, WSDL, WS-Security, WS-Addressing, TLS en SSL gebruik gemaakt van dezelfde industriestandaarden als binnen DK-WUS. 5.4.2 Technisch contract Binnen KvK-WUS worden alle voorschiften m.b.t. dit punt zoals aangegeven binnen DK-WUS gevolgd. 5.4.3 Adressering Binnen KvK-WUS worden alle voorschiften m.b.t. dit punt zoals aangegeven binnen DK-WUS gevolgd. 5.4.4 Binaire data Binnen KvK-WUS is er vooralsnog geen ondersteuning voor het omgaan met binaire data. 5.4.5 Point-to-point beveiliging Binnen KvK-WUS worden alle voorschiften m.b.t. dit punt zoals aangegeven binnen DK-WUS gevolgd. 5.4.6 End-to-end beveiliging Binnen KvK-WUS worden alle voorschiften m.b.t. dit punt zoals aangegeven binnen DK-WUS gevolgd. 5.4.7 Naamgeving Er zijn geen aanvullende eisen voor dit onderwerp binnen de koppelvlakstandaard DK-WUS. 5.4.8 Foutafhandeling Er zijn geen aanvullende eisen voor dit onderwerp binnen de koppelvlakstandaard DK-WUS.
Pagina 7 van 7
Kamer van Koophandel Nederland
