Inleiding

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.

We hanteren de regel 1 certificaat per unieke combinatie organisatie-toepassing-omgeving-aanroepende_toepassing, waarbij

• organisatie: de naam/ID van uw bedrijf
• toepassing = altijd dov-services
• omgeving: productie of oefen
• aanroepende toepassing: de naam van uw interne toepassing

Het gebruik van 1 certificaat per unieke combinatie, betekent dat:

• per toepassing die u heeft en die wil communiceren met de beveiligde DOV-services, u een afzonderlijk certificaat dient te gebruiken
• indien u gebruik wil maken van een testomgeving, om bijvoorbeeld uw eigen flow wil testen zonder de productiedata te beïnvloeden, dient u hiervoor ook een afzonderlijk certificaat te gebruiken. Het testen van flows kan op de oefenomgeving.

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. 

Aansluitingsaanvraag

Het administratieve proces om gebruik te kunnen maken van de DOV-services bestaat uit 2 stappen:

1. Aanvraag toegang DOV-services
2. Aanmaken certificaat

Stap 1. Aanvraag tot toegang tot DOV-webservices

Stuur een mail naar meldpunt@dov.vlaanderen.be waarin u volgende gegevens vermeldt:

• de naam van uw bedrijf
• de naam van applicatie die gebruik wil maken van de beveiligde DOV-webservices
• de unieke identificatie van uw organisatie
  
  • voor VO-entiteiten: de interne code
  • voor economische actoren: het KBO-nummer
  • voor organisaties die binnen het Organisatieregister gekend zijn: het OVO-nummer (https://overheid.vlaanderen.be/ovo-code)
• een korte beschrijving wat u precies wil doen
• aangeven of u naast een certificaat voor productie er ook één wenst voor de testomgeving.

DOV zal vervolgens een 'Common Name' (CN) opstellen en daaraan de nodige rechten toekennen tot de DOV-applicaties. Vervolgens zal DOV deze CN terugsturen. Het is zeer belangrijk dat deze CN wordt gebruikt bij het aanmaken van het certificaat, zie stap 2.

Stap 2. Aanmaken certificaat

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. Het aanmaken gebeurt in twee stappen.

Aanmaken CSR

Je zal eerst een private sleutel en CSR moeten aanmaken. Volg hiervoor de handleiding van Certificatenbeheer en maak gebruik van de CN die u van DOV ontving in stap 1 : 'Handleiding Private Sleutel en CSR aanmaken'

Opladen CSR en verkrijgen certificaat

De CSR die u heeft aangemaakt kan u opladen via Certificatenbeheer om het certificaat aan te vragen en te downloaden. Dit staat beschreven in de handleiding 'Nieuwe Handleiding Vo-DCBaaS'

• Voor het gebruik van VO-DCBaas moet de lokale beheerder van het bedrijf de rol DCBaaS Certificatenbeheerder Organisatie toekennen (noot: zie handleiding hoofdstuk 2.2.1 voor info over deze rol). Het toekennen van rollen en rechten gebeurt via https://gebruikersbeheer.vlaanderen.be. De rol DCBaaS Certificatenbeheerder Organisatie is te vinden onder het recht lokaal beheerder gebruikersrechten. De lokale beheerder van het bedrijf kan deze rol toekennen aan elke medewerker van het bedrijf (of zichzelf). Let op: na het toekennen van de rol, kan het even duren voor de rol is doorgestroomd in het systeem.
• Na het doorstromen van de rollen, kan de medewerker inloggen op de applicatie VO-DCBaas (https://dcb.vlaanderen.be). In deze toepassing kunnen de certificaten worden aangemaakt. 

Meer informatie over toegangs- en gebruikersbeheer van de Vlaamse Overheid vindt u op https://overheid.vlaanderen.be/publicaties-toegangs-en-gebruikersbeheer#ik-heb-vragen-over-vo-dcb-of-vodcbaas

Verlengen van een certificaat

Certificaten hebben maar een zekere geldigheidsduur. Eén maand voor de vervaldatum krijgt de contactpersoon hierover een mailtje: "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 herbruikt. 

Van start gaan met de DOV-webservices

Met een getekend certificaat kan je requests uitvoeren tegen de DOV REST API. Hiervoor dien je volgend stappenplan te volgen:

1. Definieer een HTTPS-connectie gebruikmakend van je certificaat
2. Stuur het request naar https://services.dov.vlaanderen.be/[APP]/[REST], waarbij 
   1. APP de applicatienaam in DOV is die je wenst aan te spreken
   2. REST het url-patroon is om gegevens op te vragen of door te sturen

Testen van certificaat

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. 

Quickstart

Java

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

Node.js

In hetzelfde quickstart-project (https://github.com/DOV-Vlaanderen/dov-services-quickstart) vind je ook een voorbeeld in Node.js

Python

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. 

• voorbeeldscript: demo_API_instrumenten_v1.1.ipynb (Python Jupyter-notebook)

Voorbeelden

Data aanleveren door boorbedrijven

Zie pagina: XML-bestanden opladen via de DOV-webservices

Data aanleveren voor grondwatermeetnet

Er is een REST-API beschikbaar voor het aanleveren van sensordata (aka hoogfrequente meetreeksen of loggerdata van instrumenten of sensoren). 

• Zie pagina: Aanleveren hoogfrequente meetreeksen (loggerdata)
• Of rechtstreeks naar de API-documentatie: https://www.dov.vlaanderen.be/portaal/api/instrument/api-guide.html
• Of gebruik de quickstart/cheatsheet van de REST-API Instrumenten
• voorbeeldscript: demo_API_instrumenten_v1.1.ipynb (Python Jupyter-notebook)