Rapport. Versiebeheer. Aan te sluiten overheidspartij Kamer van Koophandel Nederland

Transcriptie

1 aan van Rapport Aan te sluiten overheidspartij datum 7 januari 2013 kenmerk Onderwerp Technische Aansluitvoorwaarden KvK Web services voor overheidspartijen 1 Versiebeheer Versiebeheer Versienummer Datum Auteur Wijzigingen Erwin Embsen en Marco Fränkel Eerste versie, gebaseerd op document Technisch Koppelvlak KVK Web services op internet Marco Fränkel Aanpassingen n.a.v. opmerkingen Matthieu van Bommel, Chiel Drost, Wilko de Vlieger Programma HRIP Documentbeheer Productmanagement Marco Fränkel Bijlages II en III toegevoegd Marco Fränkel Toevoeging opmerking response bericht aan Marco Fränkel Toevoeging bijlage IV, aanpassing gebruikt WUS profiel Marco Fränkel Diverse kleine aanpassingen, aanpassing voorbeeldbericht bevragingen Marco Fränkel Herstructurering bijlages ter voorbereiding op splitsing WUS/ebMS Marco Fränkel Aanpassing Diginetwerk/Internet Marco Fränkel Kleine aanpassingen in Anne Schrijer Aanpassing in Marco Fränkel Aanpassing in (voetnoot) Pagina 1 van 7

2 Inhoudsopgave 1 Versiebeheer Voorwoord Inleiding Achtergrond Waarborgen kwaliteit Techniek Een netwerkaansluiting op Diginetwerk/Internet Een netwerkverbinding met het doelsysteem bij KVK NL Postbussen bij KVK NL Beveiliging Correcte berichten communiceren met KVK NL Een werkende web service bij KVK NL Bijlage I: KvK-WUS Toepassing koppelvlakstandaard SOAP WS-Addressing WS-Security SSL Testen aansluiten bevragingen PING test HelloWorld test Template berichten bij bevragingen Verschillen koppelvlakstandaarden KvK-WUS en Digikoppeling-WUS Standaarden Technisch contract Adressering Binaire data Point-to-point beveiliging End-to-end beveiliging Naamgeving Foutafhandeling... 7 Pagina 2 van 7

3 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 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 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

4 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 voor de gewenste adresseringgegevens. Pagina 4 van 7

5 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 voorgeschreven koppelvlakstandaard WUS SOAP Aangeleverde berichten moeten SOAP 1.1 compliant te zijn (zie /) WS-Addressing Voor routering gebruiken we WS-Addressing 1.0 versie (zie - 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= wsa:action= WS-Security De standaard WS-Security versie 2004/01 wordt gebruikt voor message-level security, zie Binnen het WS-Security framework maken we gebruik van het Web Services Security 3 X.509 Certificate Token Profile (zie N.b.: de gebruikte certificaten dienen te voldoen aan de eisen zoals gesteld in de beschrijvingen van de koppelvlakstandaarden 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

6 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 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 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=" xmlns:wsa=" xmlns:wsnt=" xmlns:wsse=" xmlns:xsi=" <soapenv:header> <wsse:security xmlns:wsu=" <wsse:binarysecuritytoken EncodingType=" 1.0#Base64Binary" ValueType=" wsu:id="[wsuid]">[binarysecuritytoken]</wsse:binarysecuritytoken> <ds:signature xmlns:ds=" Id="SIG-4"> <ds:signedinfo> <ds:canonicalizationmethod Algorithm=" <ec:inclusivenamespaces xmlns:ec=" PrefixList="soapenv wsa wsnt wsse xsi"/> </ds:canonicalizationmethod> <ds:signaturemethod Algorithm=" <ds:reference URI="#id-3"> <ds:transforms> <ds:transform Algorithm=" <ec:inclusivenamespaces xmlns:ec=" PrefixList="wsa wsnt wsse xsi"/> </ds:transform> </ds:transforms> <ds:digestmethod Algorithm=" <ds:digestvalue>[digestvalue]</ds:digestvalue> </ds:reference> </ds:signedinfo> <ds:signaturevalue>[signaturevalue]</ds:signaturevalue> <ds:keyinfo Id="[KeyID]"> <wsse:securitytokenreference xmlns:wsse11=" wsse11:tokentype=" wsu:id="[wsuid2]"> <wsse:reference URI="[ReferenceURI]" ValueType=" </wsse:securitytokenreference> </ds:keyinfo> </ds:signature> </wsse:security> <wsa:to>[destination]</wsa:to> <wsa:action>[action]</wsa:action> <wsa:messageid>[messageid]</wsa:messageid> </soapenv:header> <soapenv:body> <!-- Message here --> </soapenv:body> </soapenv:envelope> Pagina 6 van 7

7 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 Standaarden Binnen KvK-WUS wordt voor SOAP, WSDL, WS-Security, WS-Addressing, TLS en SSL gebruik gemaakt van dezelfde industriestandaarden als binnen DK-WUS Technisch contract Adressering Binaire data Binnen KvK-WUS is er vooralsnog geen ondersteuning voor het omgaan met binaire data Point-to-point beveiliging End-to-end beveiliging Naamgeving Er zijn geen aanvullende eisen voor dit onderwerp binnen de koppelvlakstandaard DK-WUS Foutafhandeling Er zijn geen aanvullende eisen voor dit onderwerp binnen de koppelvlakstandaard DK-WUS. Pagina 7 van 7