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 (Vlaamse overheid - Private Key Infrastructure).

We hanteren de regel 1 certificaat per unieke combinatie organisatie + te benaderen toepassing  + omgeving + aanroepende_toepassing, waarbij

  • organisatie: de domeinnaam van uw bedrijf, bv. "mijndomein.be"
  • te benaderen toepassing: voor toegang tot DOV is dit altijd "dov-services"
  • omgeving: "productie" of "oefen"
  • aanroepende toepassing: de naam van uw interne toepassing bv. "onzedatatoepassing"

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
  • om je eigen flow te testen zonder de productiedata te beïnvloeden, kan je gebruik maken van de dov-OEFEN-omgeving. Hiervoor moet je wel een afzonderlijk certificaat gebruiken. Dus bij het aanmaken van de certificaten kan je best meteen het duo aanmaken, eentje voor OEFEN, en eentje voor PROD, zodat er vlot kan omgeschakeld worden in latere fases van het project. 

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 van een certificaat via VO-DCBaaS (=het certificaatbeheer van de Vlaamse Overheid)

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 oefenomgeving.

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.

Stap 2. Aanmaken certificaat via VO-DCBaaS

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). 

Aanmaken private key en Certificate Signing Request (CSR)

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'.  

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 is een complexe procedure, gelieve onderstaande tips goed door te lezen.

  • Stap 1 (enkel voor bedrijven): ondernemingen of andere economische actoren hebben in principe geen toegang tot het Certificatenbeheer (VO-DCBaaS). Het Certificatenbeheer is namelijk in de eerste plaats opgezet voor Vlaamse overheidsorganisaties en lokale besturen. Maar uitzonderingen zijn mogelijk voor dienstverleners die in opdracht werken van de overheid of data moeten aanleveren voor hun wettelijke verplichtingen.
    • Stuur een e-mail naar vodcb@vlaanderen.be ("Toegangsaanvraag tot het Certificatenbeheer") met de volgende gegevens:
      a) Het KBO-nummer van jouw organisatie
      b) de reden waarom je toegang nodig hebt tot het Certificatenbeheer (b.v. als dienstverlener of omdat je Vlaamse certificaten moet gebruiken in het kader van een project van de Vlaamse overheid).
    • Zie ook Hoe kan ik aansluiten bij het certificatenbeheer DCBaaS
  • Stap 2: medewerkers de nodige rechten/rollen toekennen in DCBaaS: Voor het aanmaken van certificaten (en ook toepassingen) zijn een aantal specifieke rechten nodig in VO-DCBaaS. Iemand binnen het bedrijf moet deze rechten hebben. Het gemakkelijkste is als één persoon al de noodzakelijke rechten krijgt toebedeeld (al hoeft dit niet, bv. in grotere organisaties). Het is de lokale beheerder van het bedrijf die deze rollen toekent. 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.
    • Het toekennen van rollen en rechten gebeurt via https://gebruikersbeheer.vlaanderen.be.
    • Er zijn twee rollen nodig: DCBaaS Certificatenbeheerder Organisatie en DCBaaS Workflowbeheerder. (noot: zie handleiding hoofdstuk 2.2.1 of deze pagina voor info over deze rollen). 
      • Met het recht DCBaaS Certificaatbeheerder Organisatie kan je certificaten beheren.
      • Om een domein te beheren moet iemand nog het recht Workflowbeheerder hebben
      • Een toepassing (CN) beheren kan ook via het recht Workflowbeheerder of via het recht Certificatenbeheerder Organisatie.

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

    • De rol DCBaaS Certificatenbeheerder Organisatie is te vinden onder het recht lokaal beheerder gebruikersrechten. Maar voor bedrijven is die te vinden onder het recht DCBaaS Certificatenbeheerder Organisatie en  DCBaaS Workflowbeheerder (zonder onderliggende rol). Opgelet dus voor deze verwarring. Bovendien verschijnen deze rollen pas nadat het bedrijf werd toegevoegd in DCBaaS (zie stap 1). 
    • Wie is de lokale beheerder? In bedrijven is dit meestal de bedrijfsleider. Zie ook deze vraag Wie is de lokale beheerder van mijn bedrijf/organisatie?
  • Na het doorstromen van de rollen, kan de medewerker inloggen op de applicatie VO-DCBaas (https://dcb.vlaanderen.be). In deze toepassing kunnen de toepassing en certificaten worden aangemaakt met volgende stappen. Bovenaan zijn drie tabbladen te vinden: domein, toepassing en certificaat, nodig voor elk van onderstaande drie stappen (zie ook screenshot hieronder).  
  • Stap 3: registreren van het domein. Het domein moet gekoppeld worden aan je bedrijf. Er kunnen meerdere domeinen gekoppeld zijn. De goedkeuring gebeurt door beheerders van de Vlaamse Overheid, dus dit kan even duren. 
  • Stap 4: toevoegen van een toepassing bij het domein. Gebruik hiervoor de Common Name (CN). De aanvraag wordt vervolgens goedgekeurd door een medewerker met rol DCBaaS workflowbeheerder  (dit kan dezelfde persoon zijn).
  • Stap 5: aanvragen van een certificaat bij de toepassing. Gebruik hiervoor het CSR-bestand. De aanvraag wordt vervolgens goedgekeurd door een medewerker met rol DCBaaS workflowbeheerder (dit kan dezelfde persoon zijn).

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)

Verlengen van een certificaat

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. 

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:

testing certificates
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 

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. 

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). 


  • Geen labels