Handleiding technisch aansluiten op Digimelding Webservice

1. Inleiding

Doelgroep

Deze handleiding richt zich enerzijds op ICT-leveranciers die de applicatie van hun klanten (overheidsorganisaties) willen aansluiten op Digimelding Webservice.

Anderzijds richt de handleiding zich op overheidsorganisaties die hun applicatie zonder tussenkomst van derden (ICT-leverancier) willen aansluiten op Digimelding Webservice. 

Beiden doelgroepen worden, zodra ze aangesloten willen worden, in dit document benoemd met de term “Aanvrager” en/of “Afnemer”. 

Scope 

Deze handleiding beperkt zich alleen tot het inrichten en het testen van de aansluiting van de terugmeldvoorziening van de ICT-leverancier of de overheidsorganisatie in combinatie met Digimelding Webservice. De inrichting van het samenstellen van de terugmeldingen door de Lokale taakapplicatie van de klant en de testen met de Landelijke Voorzieningen na de aansluiting, vallen buiten scope.

Begeleiding bij aansluiten

Heeft u vragen over het aansluittraject? Bel dan met Logius. Wij helpen u graag verder. 

• Telefoon: 0900 555 45 55 (10 ct p/m)
• E-mail : servicecentrum@logius.nl

Bekijk alle documenten die u voor het aansluiten nodig heeft.

Begeleiding bij het technisch aansluiten

Heeft u vragen of hulp nodig bij het technisch aansluitproces? Neem dan contact op met het Logius Technisch Aansluitteam, hierna te noemen als Logius TA.

Het Logius TA wordt vervuld door een leverancier van Logius. In het document wordt het Logius TA in het (technisch) aansluitproces ook wel ‘Logius’ genoemd. 

U wordt gedurende het aansluitproces in contact gebracht met de contactpersonen uit het Logius TA

2. Voorwaarden 

Het aansluitdocument beschrijft alle handelingen die u als ICT-leverancier of aansluitende overheidsorganisatie moet uitvoeren om de applicatie die uw klant of u gebruikt, met succes via Digikoppeling op Digimelding Webservice aan te sluiten. Voordat u begint moet u aan een aantal voorwaarden voldoen. De voorwaarden staan hieronder beschreven. 

Digikoppeling

Voor er aangesloten kan worden op Digimelding Webservice moet de organisatie Digikoppeling compliant zijn. Bekijk meer informatie over het (implementeren van) Digikoppeling.

Digimelding Webservice maakt gebruik van het koppelvlak DMKS WUS volgens profiel 2W-be-S. In essentie houdt dat het gebruik van SOAP over HTTPS in, waarbij de verbinding verplicht gebruik maakt van een tweezijdig ingeregeld TLS1.2 protocol. Volgordelijkheid en betrouwbare aflevering worden niet afgedwongen (best effort) en het verkeer over de verbinding wordt beveiligd door het met behulp van certificaten te ondertekenen.

PKI-Overheid certificaat

Met behulp van PKI-certificaten is de informatie die personen en organisaties over het internet sturen, beveiligd op een hoog niveau van betrouwbaarheid. Het PKI-Overheid certificaat heeft u nodig bij het opbouwen van de verbinding met Digimelding Webservice, maar ook voor het ondertekenen van berichten. Aangetekend daarbij dat het technisch mogelijk is hetzelfde PKIO certificaat te gebruiken voor zowel de verbinding als voor het ondertekenen, maar dat het de voorkeur heeft om daarvoor twee verschillende certificaten te gebruiken.

Let op!

In het certificaat moet het HandelsRegisterNummer (HRN) of Organisatie Identificatie Nummer (OIN) van de organisatie zijn opgenomen en in de Common Name (CN) van het servercertificaat moet de FQN* van de server staan (beide waarden te vinden in het subjectveld van het certificaat). Voor meer informatie zie: Gebruik en Achtergrond Digikoppeling Certificaten. 

*Er zijn uitzonderingen, zie: https://tools.ietf.org/html/rfc5280#section-4.2.1.6

Preproductie en Productieomgeving

Het aansluittraject voor Digimelding Webservice bestaat uit een aansluiting eerst op de Preroductieomgeving en daarna op de Productie omgeving. Hierdoor heeft de aanvrager ook 2 omgevingen nodig die elk afzonderlijk kunnen communiceren met de betreffende Webservice endpoints. 

Vereiste SHA settings WS-Security Configuration

Wat betreft de aansluitende applicatie graag aandacht voor het volgende.

Let op!

Qua WS-Security Configuration vereist Digimelding de volgende SHA-settings:

• “signature-algorithm=
  
  http://www.w3.org/2001/04/xmldsig-more#rsa-sha256”
• “digest-algorithm=http://www.w3.org/2001/04/xmlenc#sha256”.

3. Achtergrondinformatie Digimelding Webservice

Overzicht van Digimelding Webservice

Overheidsorganisaties zijn verplicht om bij gerede twijfel over de correctheid van een gegeven dit terug te melden aan de betreffende basisregistratie. De Digimelding Webservice is de webservice van Logius waarop centraal terugmeldingen gedaan kunnen worden aan de TerugMeldVoorzieningen (TMV) van alle aangesloten (basis)registraties. 

Dit terugmelden kan op twee manieren: via het Digimelding portaal en via terugmeldfaciliteiten gebaseerd op Digimelding Webservice. De webservice biedt dezelfde berichtgevingsmogelijkheiden als de Portalen van de basisregistraties.

Figuur 1 - overzicht Digimelding Webservice

Deze handleiding richt zich op het tot stand brengen van de hierboven rood getekende koppeling tussen ‘Lokale taakapplicatie’ en ‘Digimelding Webservice’.

Het terugmelden op (basis)registraties via Digimelding Webservice vindt plaats middels elektronisch berichtenverkeer. Ten behoeve van dit verkeer zijn koppelingen nodig tussen de lokale taakapplicatie van de aanvrager en Digimelding Webservice. Het betreft hier ‘system-to-system’-koppelingen, waartoe Digimelding Webservice een koppelvlak DMKS (DigiMelding Koppelvlak Standaard) op basis van WUS (WSDL, UDDI en Soap, waarbij overigens UDDI niet gebruikt wordt) biedt.

Digimelding Webservice interfaces

Digimelding Webservice kent twee verschillende interfaces:

• De Annotatieinterface, waarin de daadwerkelijke terugmeldingen kunnen worden ingediend op de deelnemende terugmeldvoorzieningen, en status- en detail ervan kan worden opgevraagd.
• De Catalogusinterface, waarmee per deelnemende terugmeldvoorziening de catalogus met attributen kan worden opgevraagd waarop kan worden teruggemeld.

Annotatieinterface

De annotatieinterface wordt beschikbaar gesteld op deze endpoints:

Omgeving	Endpoint
Preproductieomgeving	https://preprod.services.digimelding.nl/api
Productieomgeving	https://services.digimelding.nl/api

De interface wordt beschreven door de volgende WSDL:

Omgeving	Beschrijving
Preproductieomgeving	https://preprod.services.digimelding.nl/api/koppelvlak?WSDL
Productieomgeving	https://services.digimelding.nl/api/koppelvlak?WSDL

Let op: de interface is alleen te benaderen met een geldig PKIoverheid certificaat.

In appendix A is de Preproductieversie van deze WSDL weergegeven, De Preproductie- en de Productieversie zijn, met uitzondering van de inhoud van tags schema location en address location, identiek. Het verschil is de “preprod.” in de gebruikte https-locaties binnen genoemde tags. In de productieversie ontbreekt de ”preprod.”. 

De bijbehorende namespace is: http://webservices.digimelding.nl/dmks/cookiebox/

Deze schema-files completeren de interfacebeschrijving: 

• dmks_020x_berichten.xsd
• dmks_020x_types.xsd

Op het moment van schrijven van dit document is de versie nummering van de schema files dmks_0206 voor productie omgeving en dmks_0206 voor de preproductie omgeving, dit wordt verhoogd bij volgende releases.

Deze bijbehorende schema files zijn hier te vinden:

Omgeving	Beschrijving
Preproductieomgeving	https://preprod.services.digimelding.nl/api/koppelvlak?xsd=dmks_0206_berichten.xsd
Preproductieomgeving	https://preprod.services.digimelding.nl/api/koppelvlak?xsd=dmks_0206_types.xsd
Productieomgeving	https://services.digimelding.nl/api/koppelvlak?xsd=dmks_0206_berichten.xsd
Productieomgeving	https://services.digimelding.nl/api/koppelvlak?xsd=dmks_0206_types.xsd

De volgende operations maken deel uit van dit interface:

• AnnotatieToevoegen
  • Action: AnnotatieToevoegenRequest
  • Action: AnnotatieToevoegenResponse
• Statusoverzicht
  • Action: StatusoverzichtRequest
  • Action: StatusoverzichtResponse
• DetailsTerugmelding
  • Action: DetailsTerugmeldingRequest
  • Action: DetailsTerugmeldingResponse
• Echo
  • Action: EchoRequest
  • Action: EchoResponse

Catalogusinterface

De catalogusinterface wordt beschikbaar gesteld op deze endpoints:

Omgeving	Endpoint
Preproductieomgeving	https://preprod.services.digimelding.nl/api
Productieomgeving	https://services.digimelding.nl/api

Het interface wordt beschreven door de volgende WSDL:

Omgeving	Beschrijving
Preproductieomgeving	https://preprod.services.digimelding.nl/api/catalogus?WSDL
Productieomgeving	https://services.digimelding.nl/api/catalogus?WSDL

In appendix B is de Preproductieversie van deze WSDL weergegeven, De Preproductie- en de productieversie zijn, met uitzondering van de inhoud van tags schemalocation en address location, identiek. Het verschil is de “preprod.” in de gebruikte https-locaties binnen genoemde tags. In de productieversie ontbreekt de ”preprod.”. 

De bijbehorende namespace is: http://catalogus.digimelding.nl/webservice/

Deze schema-files completeren de interfacebeschrijving:

• catalogus_010x_berichten.xsd
• catalogus_010x_types.xsd

Op het moment van schrijven van dit document is de versie nummering van de schema files catalogus_0103 voor productie omgeving en catalogus_0103 voor de preproductie omgeving, dit wordt verhoogd bij volgende releases.

Deze bijbehorende schema files zijn hier te vinden:

Omgeving	Beschrijving
Preproductieomgeving	https://preprod.services.digimelding.nl/api/catalogus?xsd=catalogus_0103_berichten.xsd
Preproductieomgeving	https://preprod.services.digimelding.nl/api/catalogus?xsd=catalogus_0103_types.xsd
Productieomgeving	https://services.digimelding.nl/api/catalogus?xsd=catalogus_0103_berichten.xsd
Productieomgeving	https://services.digimelding.nl/api/catalogus?xsd=catalogus_0103_types.xsd

In appendix B zijn deze bijbehorende schema files eveneens opgenomen.

Dit interface omvat de volgende operation:

• Opvragen
  • Action: CatalogusRequest
  • Action: CatalogusResponse

Aansluithulpmiddelen

Ter ondersteuning van het aansluitproces is er een testhulpmiddel ontwikkeld waarmee de basisfunctionaliteit van een aansluiting op Digimelding Webservice vanuit de omgeving van de lokale taakapplicatie van de klant kan worden getest.

Er is berichtenset ontwikkeld in SoapUI. Deze set bevat voorbeeld berichten, die richting de preproductie omgeving van Digimelding getest kunnen worden. 

Na goedkeuring van een aanvraag om de lokale taakapplicatie van de klant te mogen aansluiten op Digimelding Webservice worden ditvoorbeeldproduct in een aansluitkit kosteloos ter beschikking gesteld. Met dit hulpmiddel kan in eerste instantie de infrastructuur van de klant ingericht worden totdat het gekozen voorbeeldproduct werkt. Daarna kan de eigen oplossing tegen deze zelfde infrastructuur worden geplaatst. Omdat de infrastructuur dan al heeft bewezen te werken kan daarna de focus gelegd worden op het werkend krijgen van de aangeboden lokale taakapplicatie van de klant.

4. Aanvraag

Stap 1: Aanvraag 

Voordat er begonnen kan worden aan het aansluittraject zal het Logius Aansluitteam eerst de aanvraag moeten goedkeuren. Na akkoord worden de juiste mensen met elkaar in contact gebracht. Dit proces wordt hieronder beschreven.

Stap	Actiehouder	Omschrijving
1a	Aanvrager	Om het aansluittraject te starten moet eerst een aanvraag tot aansluiten op Digimelding Webservice bij Logius worden ingediend door het webformulier in te vullen via: https://www.logius.nl/diensten/digimelding/aanvragen
1b	Logius Aansluitteam	Als de aanvraag ontvangen is, zal Logius de aanvraag registreren en in behandeling nemen.
1c	Logius aansluitteam	Logius zal beoordelen of de aanvrager kan worden geaccepteerd om aan te sluiten op Digimelding Webservice.
1d	Logius aansluitteam	Bij niet akkoord zal Logius contact opnemen met de aanvrager en dit toelichten.
1e	Logius TA	Bij akkoord wordt een technisch aansluitcoördinator gekoppeld met de aanvrager.

5. Aansluiten op Digimelding Webservice Preproductie

Hieronder staat een beschrijving van de stappen die nodig zijn om de Digikoppeling aansluiting op de Digimelding Webservice Preproductieomgeving te realiseren. De onderstaande beschreven stappen kunnen grotendeels parallel uitgevoerd worden. Indien stappen wel een afhankelijkheid hebben, staat dit aangegeven. 

Stap 2: Opstellen plan van aanpak Preproductie

Voordat er aan het aansluittraject op Digimelding Webservice Preproductie begonnen wordt, moet er een plan van aanpak opgesteld worden door de aanvrager. Logius heeft hiervoor een template opgesteld. 

Hierin staan alle activiteiten die benodigd zijn voor een aansluiting op Digimelding Webservice. De aanvrager moet aan alle activiteiten een resource en een datum koppelen.

Stap	Actiehouder	Omschrijving stap
2a	Aanvrager en Logius	Informatiesessie waarin de aanvrager vragen kan stellen over het aansluitproces op Digimelding Webservice Preproductie.   Na deze informatiesessie zal de aanvrager genoeg informatie moeten hebben om tot een plan van aanpak te komen.
2b	Aanvrager	De aanvrager schrijft plan van aanpak en stuurt dit naar Logius.
2c	Logius Aansluitteam en Aanvrager	Logius Aansluitteam controleert het plan van aanpak en stemt de planning met de aanvrager af.

Stap 3: Voorbereidingen Aanvrager

Stap 3a: Randvoorwaarden inrichten

Om verder te kunnen met het aansluitproces moet eerst aan de voorwaarden (beschreven in hoofdstuk 2) voldaan zijn.

Voor de Preproductie aansluiting zijn er de volgende voorwaarden:

• In het bezit zijn van een OIN
• Een Preproductieomgeving met gekoppelde Domeinnaam
• In het bezit zijn van PKI-Overheid certificaten voor de Preproductieomgeving

Stap 4: Configuratie omgeving Aanvrager

Stap 4a: Configuratie certificaten

Truststore inrichten

Voor de Preproductieomgeving gebruikt Digimelding Webservice een PKI-Overheid certificaat. Zorg bij de inrichting van de truststore ervoor dat het (publieke) PKI-Overheid certificaat van Digimelding Webservice met bijbehorende chain wordt vertrouwd. De chain die je moet vertrouwen voor Digimelding Webservice staat hieronder beschreven met een link om ze te downloaden:

• Staat der Nederlanden Private Root CA – G1
• Staat der Nederlanden Private Services CA – G1
• KPN BV PKI-Overheid Private Services CA – G1

Het publieke certificaat van de Preproductieomgeving kan verkregen worden door de HTTPS koppelvlakpagina te benaderen via een browser. Hieronder het adres van de koppelvlakpagina waaronder de webservices aangeboden worden.

Omgeving	Netwerk	Koppelvlakpagina adres
Preproductie	Internet	https://preprod.services.digimelding.nl/api/

Mogelijk vertrouwt uw browser deze stamcertificaten niet, via de link https://www.logius.nl/diensten/pkioverheid/stamcertificaat-installeren kunt u nogmaals nalezen wat er moet gebeuren om deze certificaten te vertrouwen. 

In de ondersteunde moderne browsers (de meest recente versie en één versie daaraan voorafgaand) kunnen deze certificaten worden toegevoegd aan de vertrouwde bronnen.

Voor Microsoft Internet Explorer gebeurt dit bijvoorbeeld als volgt:

1. Start Internet Explorer.
2. Browse naar het weergegeven koppelvlakpagina adres. Er wordt een beveiligingswaarschuwing voor de website weergegeven.
3. Klik op Doorgaan naar deze website (niet aanbevolen).
4. Klik rechts van het domeinnaamadres op de werkbalk op Certificaatfout. Er verschijnt een waarschuwing dat het certificaat niet vertrouwd is.
5. Klik op Certificaat weergeven en daarna op OK.
6. Klik op Certificaat installeren.
7. Klik op Volgende in de wizard Certificaat importeren om de standaardinstellingen te accepteren.
8. Klik op Alle certificaten in het onderstaande archief opslaan en daarna op Bladeren. Selecteer Vertrouwde basiscertificeringsinstanties en klik daarna op OK.
9. Klik op Volgende en daarna op Voltooien. Er verschijnt een beveiligingswaarschuwing waarbij wordt gevraagd of u het certificaat wilt installeren
10. Klik op Ja. Er wordt bevestigd dat het certificaat is geïmporteerd. Klik op OK.
11. Klik op OK om het dialoogvenster Certificaat te sluiten.
12. Sluit de browser af en start deze opnieuw op.

Stap 5: Connectiviteit testen Aanvrager

Nadat de configuraties zijn gedaan moeten we de connectiviteit testen. De eerste stap is om de connectiviteit van de aanvrager naar het web-adres van Digimelding Webservice te testen. 

De connectiviteitstest van Digimelding Webservice naar de aanvrager wordt later in het proces getest. 

Om de connectiviteit te testen moet u vanaf de server een telnet sessie opzetten op poort 443 naar de webserver van Digimelding Webservice. Gebruik hiervoor het webserver adres zonder “https://” gedeelte, dus ‘telnet preprod.portaal.digimelding.nl 443’.

Stap	Actiehouder	Omschrijving stap
5a	Aanvrager	Aanvrager test of de Digimelding webserver vanaf de eigen server bereikbaar is door een telnet sessie op te zetten.
5b	Aanvrager	Als de telnet sessie succesvol is dan zijn we klaar. Kan de telnet sessie niet opgezet worden. Dan moeten we gaan troubleshooten.
5c	Aanvrager	Bij Digimelding Webservice staat de firewall open voor een telnet sessie. Dit betekent dat als de test faalt het connectiviteitsprobleem aan de aanvragerskant ligt.
5d	-	De connectiviteit testen zijn succesvol afgerond en er kan begonnen worden aan de volgende stap.

Stap 6: Configuratie omgeving Digimelding Webservice 

Nadat de voorbereidingen, configuraties en testen bij de aanvrager zijn gedaan, is het Logius TA aan de beurt. Het Logius TA heeft hiervoor wel gegevens van de aanvrager nodig. Hiervoor is een technisch aansluitformulier gemaakt waarin alle benodigde gegevens worden gevraagd die het Logius TA nodig heeft om de aanvrager op Digimelding Webservice Preproductie aan te sluiten.

Stap	Actiehouder	Omschrijving stap
6a	Aanvrager	De aanvrager vult het technisch aansluitformulier in. Deze heeft hij ontvangen van de aansluitcoördinator.
6b	Aanvrager	De aanvrager werkt indien nodig het plan van aanpak bij en stuurt deze samen met het technisch aansluitformulier op naar de aansluitcoördinator.
6c	Logius TA	De technische aansluitcoördinator controleert de beide documenten.
6d	Logius TA	Als beide documenten in orde zijn, wordt de aansluiting bij het technische aansluitcoördinator ingepland.
6e	Logius TA	De technische aansluitcoördinator zal binnen Digimelding Webservice het OIN van de aanvrager in de whitelisting opnemen.

Stap 7 is vervallen

Stap 8: TLS connectie testen

Deze test kan pas uitgevoerd worden als de connectiviteit in beide richtingen in orde is door stap 5 uit te voeren. 

Met de TLS test, test u of de aanvrager de juiste certificaten bezit (en of deze juist geconfigureerd zijn) en vertrouwd worden (truststore). Als aanvrager moet u namelijk het juiste publieke certificaat meesturen en het publieke certificaat van Digimelding Webservice vertrouwen. Deze test kunnen we eenzijdig uitvoeren, maar moet wel samen onderzocht worden indien deze faalt. 

Hieronder een schematisch overzicht van de TLS communicatie die plaatsvindt tussen cliënt en server.

Stap	Actiehouder	Omschrijving stap
8a	Logius TA	De technische aansluitcoördinator zet via openSSL een TLS verbinding op naar de webserver van de aanvrager. Met deze test haalt het aansluitteam het publieke certificaat en de truststore van de aanvrager op.
8b	Logius TA	Met de vorige stap kan de technische aansluitcoördinator voor de aanvrager controleren of de CA-lijst in de truststore volledig is voor de gebruikte chain in het servercertificaat van Digimelding Webservice, en of het publieke certificaat van de aanvrager de volledige en correcte chain bevat.
8c	Logius TA en Aanvrager	Indien dit niet in orde is, moet de aanvrager de (certificaten)configuratie aanpassen. Daarna kan de test nogmaals door het technische aansluitteam uitgevoerd worden. Als de test succesvol is, is de TLS test afgerond.
8d	-	De connectiviteit testen zijn succesvol afgerond en er kan begonnen worden aan de berichtenverkeertesten

Stap 9: Inrichten testhulpmiddelen

Afhankelijk van de soort softwareomgeving waarin de lokale taakapplicatie van de aanvrager functioneert, kiest de aanvrager voor het beschikbare testhulpmiddel:

• SoapUI set, opgenomen in de bijlagen in bestand  SoapUI_DigiMelding_WebServices_PP1_v2.4.7z: een testset die in de vrij te gebruiken open source variant van het SmartBear product SoapUI geïmporteerd kan worden. Bedoeld voor Java gebaseerde omgevingen.

Uiteraard kan de aanvrager er ook voor kiezen om dit testhulpmiddel niet te gebruiken en de gewenste testberichten op een andere manier aan te bieden.

Stap 9a: Inrichten SoapUI testset

Benodigdheden:

• SmartBear SoapUI Open Source, de downloadlink is op het moment van schrijven te vinden op pagina: https://www.soapui.org/downloads/soapui.html
• Een tool om .xml bestanden te kunnen bewerken. De Open Source editor Notepad++ is hiervoor zeer geschikt. De downloadlink is op het moment van schrijven te vinden op pagina: https://notepad-plus-plus.org/download/v7.5.3.html
• Een geldig en bruikbaar PKI-Overheid certificaat of Logius testcertificaat (met daarin de private key, en wachtwoord-beveiligd)

Bij het opstellen van deze handleiding is gebruik gemaakt van SoapUI (x64) versie 5.6.0 (Build Date: 2020-07-09T20:35:07Z ) onder MS-Windows 10. Per versie en/of operating system kunnen er afwijkingen zijn. 

Download en installeer SoapUI. De installatie die voor deze handleiding gebruikt is, werd geïnstalleerd in map: "C:\Program Files\SmartBear\SoapUI-5.6.0\" (door de installer zelf gekozen). 

In de paragraaf ‘Extra configuratiestappen SoapUI’ een aantal bijzonderheden vermeld die geldig waren voor de hier gebruikte SoapUI versie, maar in een andere versie wellicht niet aan de orde zijn.

Importeren testset Digimelding Webservice

De SoapUI testset voor Digimelding Webservice wordt aangeleverd als een 7zip bestand met de naam “SoapUI_DigiMelding_WebServices_PP1_vx.y.7z”, waarbij x.y een versie aangeven. De meest recente versie op het moment van schrijven is 2.4.

In het 7zip bestand zitten twee bestanden verpakt:

• Instructie Inlezen SoapUI project DigiMelding-vx.y.txt
• STD_DGM_Webservices_PP1_vx.y-soapui-project.xml

Beide bestanden moeten uitgepakt worden naar een zelf te kiezen map. Bij het samenstellen van deze handleiding is hiervoor de map “C:\SoapUIProjects\” gebruikt.

Het tekstbestand “Instructie Inlezen SoapUI project DigiMelding-vx.y.txt” bevat dezelfde informatie als hier in deze paragraaf weergegeven. In toekomstige versies (later dan 2.4) zou hierin aanvullende informatie, specifiek voor die betreffende versie, opgenomen kunnen zijn die in deze paragraaf niet genoemd is.

In het STD_DGM_Webservices_PP1_vx.y-soapui-project.xml bestand moeten nu de volgende stappen worden uitgevoerd met behulp van een tekst-editor (zoals Notepad++):

• Zoek alle voorkomsten van de tekst "certificate.p12" en vervang die door de exacte bestandsnaam van uw eigen certificaat.
• Zoek alle voorkomsten van de tekst "uwCertificaatWachtwoord" en vervang die door het wachtwoord van uw eigen certificaat.
• Zoek alle voorkomsten van de tekst "uwCertificaatSubject_CN" en vervang die door de Common Name van het Subject van uw eigen certificaat (dit is meestal een tekenreeks waarin de naam van uw organisatie herkenbaar is).
• Zoek alle voorkomsten van de tekst "uwOrganisatieOIN" en vervang die door het OIN van uw eigen organisatie.

Sla het STD_DGM_Webservices_PP1_vx.y-soapui-project.xml bestand weer op en sluit de tekstverwerker af.

Start SoapUI en ga naar de "Preferences". Kies daarin voor de "SSL settings":

Stel hier de "KeyStore" in zodat deze wijst naar uw eigen certificaat. Vul het wachtwoord van uw certificaat in bij "KeyStore Password". Zorg dat het vakje "Client Authentication" is aangevinkt. Alle overige velden kunnen leeg/niet aangevinkt blijven.

Kies nu onder menuoptie "File" voor "Import Project":

Wijs het zojuist bewerkte bestand "STD_DGM_Webservices_PP1_vx.y-soapui-project.xml" aan. Tijdens het importeren kan een "Resolve Project" melding gegeven worden (dit gebeurt als het certificaat bestand niet op dezelfde plaats staat als het XML bestand). Deze melding zegt dan dat het certificaat bestand ontbreekt. Kies in dat geval onder "Action" voor "Select File" en wijs het certificaatbestand aan.

Extra configuratiestappen SoapUI

Aanpassing van de Java versie

De standaard installatie van SoapUI installeert ook een eigen kopie van de Java Runtime Engine (JRE), deze werd bij de hier gebruikte installatie  geplaatst in de map: "C:\Program Files\SmartBear\SoapUI-5.6.0\jre\".

Tijdens opstarten van SoapUI en uitvoeren van tests zullen fouten en warnings in de SoapUI log (te zien in het desbetreffende tabblad) gepresenteerd worden, zoals:

ERROR:An error occurred [com.eviware.soapui.plugins.auto.factories.AutoDiscoveryMethodFactory], see error log for details

ERROR:An error occurred [com.eviware.soapui.plugins.auto.factories.AutoImportMethodFactory], see error log for details

WARN:Using fallback method to load keystore/truststore due to: Invalid keystore format

Hoewel dit de uiteindelijke werking niet stoort kan het wel als storend worden ervaren door de klant. Het is gebleken dat het gebruik van een andere (recente) JRE (Java 8 in ons geval) dit fenomeen geheel oplost. 

Om dit te bereiken is de (op dat moment) meest recente versie van de JRE geïnstalleerd. Let er daarbij op dat dezelfde machine-architectuur wordt gekozen als die van SoapUI. In ons geval werd de 64bit (x64) versie van SoapUI gebruikt, en dus ook de 64bit versie van de JRE (installer: jre-8u151-windows-x64.exe). Laat deze JRE installeren op de locatie die door de installer zelf wordt gekozen, of een andere locatie naar keuze (maar niet op de plaats waar SoapUI de eigen JRE heeft staan: "C:\Program Files\SmartBear\SoapUI-5.6.0\jre\"). 

Als hierna de map "C:\Program Files\SmartBear\SoapUI-5.6.0\jre\" wordt hernoemd in "C:\Program Files\SmartBear\SoapUI-5.6.0\jre.disregard\" dan zorgt het opstartmechanisme van SoapUI ervoor dat de nieuw geïnstalleerde JRE wordt gebruikt in plaats van de meegeleverde versie van SoapUI. 

Ter info: het opstartmechanisme van SoapUI wordt (in MS-Windows) gestuurd door een batch-bestand: "C:\Program Files\SmartBear\SoapUI-5.6.0\bin\soapui.bat", maar hierin hoeft dus niets te worden aangepast mits de “...\jre\” folder onder SoapUI hernoemd wordt zoals hierboven beschreven. 

In ons geval blijkt er wel verschil te ontstaan in de omgang met het signing certificate: met de originele JRE werd het "alias" van de "signature" keystore automatisch gezet op de Common Name (CN) uit het subject van het certificaat. Met de nieuwe JRE wordt de "alias" niet gevuld, waarschijnlijk omdat in het betreffende certificaat het alias de fysieke naam "1" heeft (als het bekeken wordt met Keytool of met Keystore Explorer), en niet meer de Common Name uit het subject van het certificaat. 

Bij het insturen van een bericht ontstaat hierdoor deze foutmelding:

ERROR:An error occurred [General security error (No certificates for user 'CN uit certificaat' were found for signature)], see error log for details

Om dit goed te krijgen moet het volgende worden gedaan in het geïmporteerde project:

1. Klik het project aan en kies in het menu voor "Project" -> "Show Project View"
2. Kies het tabblad “WS-Security Configurations” en daarin "Outgoing WS-Security Configurations"
3. Kies daarbinnen de configuratie "out"
4. In het linker venstertje onder de configuraties staan twee entries: "Timestamp" en "Signature". Selecteer "Signature"
5. In het rechter venstertje onder de configuraties is de dropdown bij "Alias" leeg (dit kan anders zijn in het geval van een ander certificaat)
6. Kies in deze dropdown het gewenste alias (in ons geval was dat "1", wat tevens de enig aanwezige waarde was):

Hierna werkt de communicatie weer (vergeet niet deze wijziging te laten opslaan door SoapUI).

Aanpassing TLS versie

In principe vereist de specificatie het gebruik van tweezijdig TLS 1.2 om aan te sluiten op de webservices van Digimelding. Standaard maakt de toegepaste SoapUI versie gebruik van TLSv1 (dus TLS versie 1.0). Op dit moment is communicatie naar Digimelding Webservice met tweezijdig TLSv1 nog wel mogelijk, maar dat zal op termijn aangepast gaan worden naar het afdwingen van tweezijdig TLSv1.2.

Om SoapUI te dwingen gebruik te maken van TLSV1.2 moet het volgende gedaan worden:

• In de map "C:\Program Files\SmartBear\SoapUI-5.6.0\bin\" bevindt zich een bestand "SoapUI-5.6.0.vmoptions", maak hiervan vooraf een veiligheidskopie zodat de originele inhoud bij behoefte weer hersteld kan worden.
• voeg in het originele bestand aan het einde deze regel toe (bijvoorbeeld met behulp van Notepad++) : "-Dsoapui.https.protocols=TLSv1.2" (zonder de double-quotes) en sla het bestand weer op.

Als nu SoapUI wordt gestart zal TLSv1.2 gebruikt worden.

Gebruik van een recentere SoapUI versie

Inmiddels is er een nieuwere SoapUI versie uitgebracht, SoapUI versie 5.6.0.

Deze versie wordt gebundeld met een Java 8 runtime, maar de genoemde fouten en warnings uit de vorige paragraaf “Extra configuratiestappen SoapUI” treden ook daarmee nog steeds op. De genoemde oplossing (installatie van een andere java JRE en hernoemen van de “...\jre\” map onder de SoapUI installatie) blijkt echter niet meer te werken. Een oplossing daarvoor is nog niet gevonden.

Wel blijkt de omgang met het signing certificate nu identiek te zijn aan hetgeen beschreven werd in de paragraaf  “Extra configuratiestappen SoapUI”. Ook de aangegeven oplossing (kiezen van de juiste Alias onder de Signature in het profiel “out”, onder de Outgoing WS-Security configurations) blijkt nog te werken zoals beschreven.

Ook het afdwingen van het gebruik van TLS1.2 zoals beschreven in de paragraaf “Extra configuratiestappen SoapUI” blijkt nog steeds te werken zoals beschreven.

Stap 10: ‘Echo’ testen 

Bij deze Echo test wordt een echo bericht verstuurd naar één van de TMV’s om te verifiëren of de gespecificeerde echo response terugkomt. Dit is de meest basale vorm van berichtuitwisseling waarbij daadwerkelijke communicatie met de Digimelding Webservice plaatsvindt.

In het geval er gebruik gemaakt wordt van de SoapUI testset dan kan hiervoor in de “Testsuite BAG” de test “Echo BAG” worden uitgevoerd.

Stap 10 a - Sturen TestEcho bericht

De aanvrager stuurt via het gebruikte testhulpmiddel een TestEcho bericht naar Digimelding Webservice. De payload die wordt meegestuurd ziet er als volgt uit:

Bovenstaande XML is als bestand “testEcho_BAG.txt” in map ‘Bijlagen’ te vinden. Een voorbeeld van de bijbehorende response is als bestand “echoResponse_BAG.txt” in map ‘Bijlagen’ te vinden.

Placeholder	Omschrijving
MessageID	Uniek berichtkenmerk
OinBasisregistratie	OIN van de basisregistratie waarop teruggemeld wordt, in dit geval waar de Echo naartoe gestuurd wordt, bijv. 00000001802327497000 voor kadaster BAG
Echo	De tekenreeks die terug gestuurd zal worden in de echoResponse: testEcho<

Stap	Actiehouder	Omschrijving stap
10b	Aanvrager	De aanvrager controleert of het echobericht resulteert in het verwachtte echo-response bericht vanuit Digimelding Webservice. Als dat bericht niet (juist) is binnengekomen gaan we troubleshooten.
10c	Aanvrager en Logius TA	Controleer bij het troubleshooten met name de foutmeldingen in het gebruikte testhulpmiddel en de meldingen in de logging van de webserver en het beheer portaal van Digimelding Webservice.
10d	-	De Echo test is succesvol afgerond.

Stap 11: ‘Catalogus opvragen’ testen 

Bij deze test wordt de catalogus opgevraagd van TMV kadaster BAG. Hierbij wordt een response terugverwacht waarin BAG alle mogelijke catalogus-items toont. 

In het geval er gebruik gemaakt wordt van de SoapUI testset dan kan hiervoor in de “Testsuite BAG” de test “OpvragenCatalogusBAG” worden uitgevoerd.

Stap 11a - Sturen catalogus Opvragen bericht

De aanvrager stuurt via het gebruikte testhulpmiddel een catalogus Opvragen bericht naar Digimelding Webservice. De payload die wordt meegestuurd ziet er als volgt uit:

Bovenstaande XML is als bestand “catalogusRequest_BAG.txt” in map ‘Bijlagen’ te vinden. 

Een voorbeeld van de bijbehorende response is als bestand “catalogusResponse_BAG_<JJJJMMDD>.txt” in map ‘Bijlagen’ te vinden. 

Opmerking: <JJJJMMDD> in de naam van het bestand refereert aan de datum waarop deze response is ontvangen.

Placeholder	Omschrijving
MessageID	Uniek berichtkenmerk
OinBasisregistratie	OIN van de basisregistratie waarop teruggemeld wordt, in dit geval waar de catalogus opvraging naartoe gestuurd wordt, bijv. 00000001802327497000 voor kadaster BAG

Stap	Actiehouder	Omschrijving stap
11b	Aanvrager	De aanvrager controleert of het catalogus opvragen verzoek resulteert in het verwachte response bericht met de catalogusitems vanuit Digimelding Webservice. Als dat bericht niet (juist) is binnengekomen gaan we troubleshooten.
11c	Aanvrager en Logius TA	Controleer bij het troubleshooten met name de foutmeldingen in het gebruikte testhulpmiddel en de meldingen in de logging van de webserver en het beheer portaal van Digimelding Webservice.
11d	-	De catalogus opvragen test is succesvol afgerond.

Stap 12: ‘Status opvragen’ testen 

Bij deze test wordt de status opgevraagd van meldingen aan TMV kadaster BAG. Hierbij wordt een response terugverwacht waarin BAG alle teugmeldingen weergeeft die in het verleden door onszelf zijn aangeboden.

In het geval er gebruik gemaakt wordt van de SoapUI testset dan kan hiervoor in de “Testsuite BAG” de test “OpvragenStatusBAG” worden uitgevoerd.

Stap 12a - Sturen status opvragen bericht naar Digimelding Webservice

De aanvrager stuurt via het gebruikte testhulpmiddel een status opvragen bericht naar Digimelding Webservice. De payload die wordt meegestuurd ziet er als volgt uit:

Bovenstaande XML is als bestand “opvragenStatus_BAG.txt” in map ‘Bijlagen’ te vinden. Een voorbeeld van de bijbehorende response is als bestand “statusResponse_BAG.txt” in map ‘Bijlagen’ te vinden.

Placeholder	Omschrijving
MessageID	Uniek berichtkenmerk
OinVragendeOrganisatie	OIN van de partij die de opvraging doet
OinBasisregistratie	OIN van de basisregistratie waarop teruggemeld wordt, in dit geval waar de opvraging naartoe gestuurd wordt, bijv. 00000001802327497000 voor kadaster BAG

Stap	Actiehouder	Omschrijving stap
12b	Aanvrager	De aanvrager controleert of het status opvragen verzoek resulteert in het verwachte response bericht met de bestaande terugmeldingen vanuit Digimelding Webservice. Als dat bericht niet (juist) is binnengekomen gaan we troubleshooten.
12c		Controleer bij het troubleshooten met name de foutmeldingen in het gebruikte testhulpmiddel en de meldingen in de logging van de webserver en het beheer portaal van Digimelding Webservice.
12d	-	De status opvragen test is succesvol afgerond.

U bent nu aangesloten op de Preproductieomgeving.

6 Aansluiten op Digimelding Webservice Productie

Hieronder staat een beschrijving van de stappen die nodig zijn om de Digikoppeling aansluiting op Digimelding Webservice productie te realiseren. De onderstaande beschreven stappen kunnen grotendeels parallel uitgevoerd worden. Indien stappen wel een afhankelijkheid hebben, staat dit aangegeven. 

De stappen voor de aansluiting op Productie zijn in grote lijnen een herhaling van de stappen op Preproductie.

Stap 13: Opstellen plan van aanpak productie

Voordat er aan het aansluittraject op Digimelding Webservice productie begonnen wordt, moet er nogmaals een plan van aanpak opgesteld voor de productieaansluiting. Logius heeft hiervoor een template opgesteld. Hierin staan alle activiteiten die benodigd zijn voor een aansluiting op Digimelding Webservice. De projectleider van de aanvrager moet aan alle activiteiten een resource en een datum koppelen.

Stap	Actiehouder	Omschrijving stap
13a	Aanvrager	De aanvrager (projectleider) schrijft plan van aanpak en stuurt deze op naar Logius.
13b	Logius Aansluitteam en Aanvrager	Aansluitteam controleert het plan van aanpak en stemt de planning met de aanvrager af.

Stap 14: Voorbereidingen Aanvrager

Stap 14a: Randvoorwaarden inrichten

Om verder te kunnen met het aansluitproces moet eerst aan de voorwaarden (beschreven in hoofdstuk 2) voldaan zijn. 

Voor de Productie aansluiting zijn er de volgende voorwaarden:

• In het bezit zijn van een OIN
• Een Productie omgeving met Domeinnaam aangekoppeld
• In het bezit zijn van het benodigde PKI-Overheid certificaat voor de Productie omgeving

Stap 15: Configuratie certificaten

Voor de productie omgeving verwijzen wij u graag naar hoofdstuk 5.3 voor de configuratie van certificaten.

Stap 15b: Configuratie firewall/proxy

Om connectiviteit mogelijk te maken, moet vaak de firewall geconfigureerd (opengezet) worden voor binnenkomend verkeer en, indien van toepassing, de proxy voor het (routeren van het) uitgaande verkeer. Hieronder het IP adres van Digimelding Webservice (productie).

Omgeving	Netwerk	Webserver DNS name	IP adres
Productie Digimelding Webservice	Internet	https://services.digimelding.nl/	144.43.243.66

Stap 16: Connectiviteit testen Aanvrager 

Nadat de configuraties zijn gedaan moeten we de connectiviteit testen. Eerste stap is om de connectiviteit van de aanvrager naar het web-adres van Digimelding Webservice te testen.

De connectiviteitstest van Digimelding Webservice naar de aanvrager wordt later in het proces getest.

Om de connectiviteit te testen moet kunt u vanaf de server een telnet sessie opzetten op poort 443 naar de webserver van Digimelding Webservice. Gebruik hiervoor het webserver adres zonder “https://” gedeelte, dus ‘telnet portaal.digimelding.nl 443’.

 

Stap	Actiehouder	Omschrijving stap
16a	Aanvrager	Aanvrager test of de Digimelding webserver vanaf de eigen server bereikbaar is door een telnet sessie op te zetten.
16b	Aanvrager	Als de telnet sessie succesvol is dan zijn we klaar. Kan de telnet sessie niet opgezet worden. Dan moeten we gaan troubleshooten.
16c	Aanvrager	Bij Digimelding Webservice staat de firewall open voor een telnet sessie. Dit betekent dat als de test faalt het connectiviteitsprobleem aan de aanvragerskant ligt.
16d	-	De connectiviteit testen zijn succesvol afgerond en er kan begonnen worden aan de volgende stap.

Stap 17: Configuratie omgeving Digimelding Webservice

Nadat de voorbereidingen, configuraties en testen bij de aanvrager zijn gedaan, is Logius TA aan de beurt. Het Logius TA heeft hiervoor wel gegevens van de aanvrager nodig. Hiervoor is een technisch aansluitformulier gemaakt waarin alle benodigde gegevens worden gevraagd die het Logius TA nodig heeft om de aanvrager op Digimelding Webservice (Productie) aan te sluiten.

Stap	Actiehouder	Omschrijving stap
17a	Aanvrager	De aanvrager vult het technisch aansluitformulier in. Deze heeft hij ontvangen van de aansluitcoördinator.
17b	Aanvrager	De aanvrager werkt indien nodig het plan van aanpak bij en stuurt deze samen met het technisch aansluitformulier op naar de aansluitcoördinator.
17c	Logius TA	De aansluitcoördinator controleert de beide documenten.
17d	Logius TA	Als beide documenten in orde zijn, wordt de aansluiting bij het aansluitteam ingepland.
17e	Logius TA	Het aansluitteam zal binnen Digimelding Webservice het OIN van de aanvrager in de whitelisting opnemen.

Stap 18 is vervallen

Stap 19: TLS connectie testen

Deze test kan pas uitgevoerd worden als de connectiviteit in beide richtingen in orde is. 

Voor de productie omgeving verwijzen wij u graag naar Stap 8: TLS connectie testen.

Stap 20: Inrichten testhulpmiddelen

Indien gewenst kan ook voor de productieaansluiting gebruik gemaakt worden van de aangeboden testhulpmiddelen.

Het inrichten van deze hulpmiddelen is identiek aan de beschrijving in de Stap 9: Inrichten testhulpmiddelen, met de volgende kleine aanpassingen:

Stap 20a: Productie aanpassing SoapUI testset

Hernoem het xml bestand “STD_DGM_Webservices_PP1_vx.y-soapui-project.xml” in “STD_DGM_Webservices_PRD_vx.y-soapui-project.xml”.

Voer nu de wijzigingen daarin uit zoals beschreven in Stap 9: Inrichten testhulpmiddelen let er daarbij op dat de gegevens gebruikt worden van het certificaat voor de productie omgeving.

Voer nu nog deze aanvullende wijzigingen uit:

• Zoek alle voorkomsten (vermoedelijk slechts één) van de tekst "_PP1_" en vervang die door "_PRD_".
• Zoek alle voorkomsten van de tekst "preprod.portaal" en vervang die door  "portaal".

Stap 21: ‘Echo’ testen 

Bij deze Echo test wordt een echo bericht verstuurd naar één van de TMV’s om te verifiëren of de gespecificeerde echo response terugkomt. Dit is de meest basale vorm van berichtuitwisseling waarbij daadwerkelijke communicatie met de Digimelding Webservice plaatsvindt.

In het geval er gebruik gemaakt wordt van de SoapUI testset dan kan hiervoor in de “Testsuite BAG” de test “Echo BAG” worden uitgevoerd.

Stap 21a - TestEcho bericht sturen naar Digimelding Webservice

De aanvrager stuurt via het gebruikte testhulpmiddel een TestEcho bericht naar Digimelding Webservice. De payload die wordt meegestuurd ziet er als volgt uit:

Bovenstaande XML is als bestand “testEcho_BAG_PRD.txt” in map ‘Bijlagen’ te vinden.

Placeholder	Omschrijving
MessageID	Uniek berichtkenmerk
OinBasisregistratie	OIN van de basisregistratie waarop teruggemeld wordt, in dit geval waar de Echo naartoe gestuurd wordt, bijv. 00000001802327497000 voor kadaster BAG
Echo	De tekenreeks die terug gestuurd zal worden in de echoResponse: testEcho

Stap	Actiehouder	Omschrijving stap
21b	Aanvrager	De aanvrager controleert of het echobericht resulteert in het verwachtte echo-response bericht vanuit Digimelding Webservice. Als dat bericht niet (juist) is binnengekomen gaan we troubleshooten.
21c	Aanvrager en Logius AT	Controleer bij het troubleshooten met name de foutmeldingen in het gebruikte testhulpmiddel en de meldingen in de logging van de webserver en het beheer portaal van Digimelding Webservice.
21d	-	De Echo test is succesvol afgerond.

Let op!

Er worden in productie geen functionele stromen getest. Dit betekent dat de berichttesten beperkt blijven tot deze echo test.

U bent klaar met de aansluiting op Digimelding Webservice.