De DOV-webservices zijn publieke API's die we aanbieden op internet en waarvoor authenticatie nodig is. De services worden standaard beveiligd met certificaten, en we gebruiken hiervoor standaard de VO-PKI (Vlaamse overheid - Private Key Infrastructure).
We hanteren de regel 1 certificaat per unieke combinatie organisatie + te benaderen toepassing + omgeving + aanroepende_toepassing, waarbij
Het gebruik van 1 certificaat per unieke combinatie, betekent dat:
In onderstaande tekst is de gebruikte terminologie vrij standaard, waarbij we er wel vanuit gaan dat de lezer voldoende kennis heeft wat betreft SSL en certificaten.
Het administratieve proces om gebruik te kunnen maken van de DOV-services bestaat uit 2 stappen:
Stuur een mail naar meldpunt@dov.vlaanderen.be waarin u volgende gegevens vermeldt:
Vervolgens wordt er een 'Common Name' (CN) afgesproken, waarmee uw applicatie zal gekend zijn zowel bij DOV als bij DCBaaS en in uw eigen omgeving. Deze CN ziet er bv. als volgt uit: "mijndomein.be/dov-services/productie/onsdataprogramma". Het eerste stuk is best het domein van uw organisatie, zodat ook andere toepassingen van uw organisatie hetzelfde domein kunnen gebruiken.
DOV zal vervolgens de Common Name van de toepassing toevoegen aan de DOV-config en daarbij de nodige rechten toekennen tot de DOV-applicaties.
In parallel zal u aan uw kant de CN moeten gebruiken voor het aanmaken van het certificaat, zie stap 2.
Het aanmaken van een certificaat is een actie die integraal door de aanvrager kan gerealiseerd worden. Het aanmaken van een certificaat gebeurt via het Certificatenbeheer (Vo-DCBaaS) van de Vlaamse Overheid. Meer info is te vinden in de handleiding van certificatenbeheer (VO-DCBaas).
Je zal eerst een private sleutel en een CSR moeten aanmaken. Het CSR is een ascii-bestandje dat Common Name (CN) en private key combineert, en waarmee vervolgens het certificaat wordt aangemaakt. Volg hiervoor de handleiding van Certificatenbeheer en maak gebruik van de CN die u van DOV ontving in stap 1. Meer info op: 'Handleiding Private Sleutel en CSR aanmaken'.
De CSR die u heeft aangemaakt kan u opladen via Certificatenbeheer om het certificaat aan te vragen en te downloaden. Dit is een complexe procedure, gelieve onderstaande tips goed door te lezen.
Ken binnen je organisatie minstens de rol DCBaaS Workflowbeheerder toe. Als je ook de rol DCBaaS Certificatenbeheerder Organisaties toekent aan dezelfde of een andere medewerker, dan kan je alle acties in het certificatenbeheer uitvoeren |
Opgelet voor wie nog met oude certificaten werkt: sinds 01/03/2021 is het nieuw Certificatenbeheer gelanceerd en dient werk gemaakt te worden van migratie bestaande certificaten. Meer info hierover op: https://overheid.vlaanderen.be/nieuws/lancering-nieuw-certificatenbeheer-vo-dcbaas-en-migratie-bestaande-certificaten
Nuttige links:
Screenshot van VO-DCBaas (bovenaan de drie tabbladen: certificaten, toepassingen en domeinen, die nodig zijn voor stap 3 tem 5)
Certificaten hebben maar een zekere geldigheidsduur. Eén maand voor de vervaldatum krijgt de contactpersoon hierover een mailtje: bvb: "Het certificaat voor toepassing omgeving.vlaanderen.be/dov-services/productie/xxxx, met certificaattype SSL Client gaat vervallen op 2023-06-07 09:55:59. Gelieve actie te ondernemen om dit certificaat tijdig te vervangen zodat uw toepassing geen dientonderbrekingen ondergaat.".
Contacteer dan de lokale beheerder of een gebruiker met de rol DCBaaS Certificatenbeheerder Organisatie. Zij moeten via webIDM een nieuw certificaat aanmaken, dat dan in de toepassing het oude zal vervangen. Voor het aanmaken van een nieuw certificaat kan het bestaande CSR-bestanden worden hergebruikt.
Met een getekend certificaat kan je requests uitvoeren tegen de DOV REST API. Hiervoor dien je volgend stappenplan te volgen:
De eenvoudigste manier om een certificaat te testen is om een cURL-commando te gebruiken:
curl -k https://services.dov.vlaanderen.be/dov-xdov-server/logs/count --key <full path to you private key> --cert <full path to your certificate> -v |
Als je een time-out krijgt, is dit mogelijk te wijten doordat je netwerkverkeer via een proxy-server verloopt. Details hierover kan je best aanvragen bij je netwerkbeheerder. De proxy-gegevens voeg je dan toe met optie -x. Zo moeten gebruikers op het netwerk van de Vlaamse overheid -x proxy.vlaanderen.be:8080 toevoegen aan bovenstaande commando.
Voor de oefen omgeving kan de url https://services-oefen.dov.vlaanderen.be/dov-xdov-server/logs/count gebruikt worden |
Er is een java quickstart-project beschikbaar dat demonstreert hoe je de DOV-services kan oproepen: https://github.com/DOV-Vlaanderen/dov-services-quickstart
Hoe je een secure connection opbouwt met een certificaat vind je specifiek in https://github.com/DOV-Vlaanderen/dov-services-quickstart/blob/master/config/src/main/java/be/vlaanderen/dov/services/config/ClientConfig.java
In hetzelfde quickstart-project (https://github.com/DOV-Vlaanderen/dov-services-quickstart) vind je ook een voorbeeld in Node.js
Het gebruik van Request met client side certificates is beschreven in bv. https://www.techcoil.com/blog/how-to-send-a-http-request-with-client-certificate-private-key-password-secret-in-python-3/.
Er is een voorbeeldscript voor het testen van certificaten en het invoeren van putten, filters en instrumenten via XML en json.
Zie pagina: XML-bestanden opladen via de DOV-webservices
Er is een REST-API beschikbaar voor het aanleveren van sensordata (aka hoogfrequente meetreeksen of loggerdata van instrumenten of sensoren).