Inleiding

De DOV-webservices zijn publieke API's. Ze worden beveiligd met certificaten, gebruik makend van de 'Vlaamse overheid - Private Key Infrastructure'.

We hanteren de regel 1 certificaat per unieke combinatie: 

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

Per toepassing die wil communiceren met de DOV-services, dient u dus een afzonderlijk certificaat te gebruiken.

Om te testen zonder de productiedata te beïnvloeden, kan je de OEFEN-omgeving gebruiken. Hiervoor is een afzonderlijk certificaat nodig. Bij het aanmaken van de certificaten kan je dus best meteen één voor OEFEN en één voor PRODUCTIE aanmaken.

Aanvraag

Stap 1. Aanvraag toegang tot DOV-webservices

Mail naar meldpunt@dov.vlaanderen.be (onderwerp: 'Aanvraag toegang tot DOV-webservices') de volgende gegevens:

  • domeinnaam van uw organisatie
  • applicatienaam die gebruik wil maken van de DOV-webservices
  • 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)
  • beschrijving van wat uw applicatie wil doen
  • omgeving, alleen productie of ook toegang tot de oefenomgeving

Vervolgens spreken we een 'Common Name' (CN) af (maximum 64 karakters). Dit is de naam waarmee uw applicatie wordt geïdentificeerd, zowel bij DOV, certificatenbeheer, als uw eigen omgeving. De CN wordt opgebouwd als domeinnaam/dov-services/omgeving/toepassing, bijvoorbeeld 'mijndomein.be/dov-services/productie/onzedatatoepassing'. Het eerste stuk bevat het domein van uw organisatie, zodat de Common Name van andere toepassingen van uw organisatie een gemeenschappelijk begin hebben.

DOV zal vervolgens de CN van uw toepassing toevoegen aan de DOV-config en daarbij de nodige rechten ('profiles') toekennen tot de DOV-applicaties. 

Stap 2. Aanmaken certificaat via certificatenbeheer

Het certificaat wordt aangemaakt via het Certificatenbeheer van de Vlaamse Overheid (VO-DCBaaS). Voor meer info zie handleiding certificatenbeheer of Handleiding pdf.

Aanmaken private sleutel en Certificate Signing Request

Om een certificaat aan te vragen bij certificatenbeheer heb je een Certificate Signing Request (CSR) nodig. Het CSR is een bestand dat wordt aangemaakt op basis van een publieke sleutel, de Common Name (zie stap 1) en identificerende informatie zoals organisatienaam en landcode. Deze informatie wordt versleuteld op basis van de aangemaakte private sleutel. De private sleutel mag nooit de machine waarop die werd aangemaakt verlaten, zo kan deze nooit via een onveilige verbinding worden verstuurd. De private sleutel (pem-bestand) in combinatie met het certificaat (crt-bestand) wordt gebruikt om je te authenticeren bij de DOV-webservices.

Het CSR-bestand wordt aangemaakt met één van volgende tools. Bewaar de private sleutel (pem-bestand) en het CSR-bestand goed.  

Aanvragen certificaat

Het aangemaakte CSR-bestand kan u via certificatenbeheer opladen om het certificaat aan te vragen.

  • Stap 1: Toegangsaanvraag Certificatenbeheer (enkel voor bedrijven)
    • Bedrijven of andere economische actoren hebben in principe geen toegang tot het Certificatenbeheer. Het Certificatenbeheer is namelijk opgezet voor Vlaamse overheidsorganisaties en lokale besturen. Uitzonderingen zijn mogelijk voor dienstverleners die in opdracht werken van de overheid of data moeten aanleveren voor hun wettelijke verplichtingen. Zie ook Aansluiten bij het certificatenbeheer.
    • Mail volgende gegevens naar vodcb@vlaanderen.be (Onderwerp 'Toegangsaanvraag tot het Certificatenbeheer'):
      • KBO-nummer van jouw organisatie
      • de reden waarom je toegang nodig hebt tot het Certificatenbeheer (bijvoorbeeld als dienstverlener of voor een project van de Vlaamse overheid).
  • Stap 2: Rechten toekennen
    • Om te kunnen inloggen en certificaten of toepassingen te beheren bij certificatenbeheer (dcb.vlaanderen.be), zijn specifieke rechten nodig.
    • De lokale beheerder van het bedrijf kan deze rechten toekennen aan medewerkers van het bedrijf (of zichzelf) via gebruikersbeheer.vlaanderen.be. Let op, na het toekennen, kan het even duren voor het recht is doorgestroomd in het systeem.
    • Er zijn twee rechten nodig: 'DCBaaS Certificatenbeheerder Organisatie' en 'DCBaaS Workflowbeheerder'. Zie handleiding hoofdstuk 2.2.1 of het rollenmodel. 
      • 'DCBaaS Certificaatbeheerder Organisatie': kan certificaten aanmaken/beheren
      • 'DCBaaS Workflowbeheerder': kan domeinen aanvragen
      • 'DCBaaS Certificatenbeheerder Toepassing': kan certificaten aanmaken/beheren voor specifieke toepassingen
        • Medewerkers van het Departement Omgeving dienen dit recht aan te vragen bij hun lokale beheerder, aangezien zij nooit het recht zullen krijgen om de certificaten van het hele departement te beheren.

    • Ken binnen je organisatie minstens het recht 'DCBaaS Workflowbeheerder' toe. Als je ook het recht 'DCBaaS Certificatenbeheerder Organisatie' toekent, kan je alle acties in het certificatenbeheer uitvoeren.

  • Stap 3: Inloggen op certificatenbeheer via dcb.vlaanderen.be 
    • Bovenaan zijn er 3 tabladen Certificaten, Toepassingen en Domeinen, nodig voor de volgende stappen.

                 

  • Stap 4: Registreren van een domein
    • Je domeinnaam is vrij te kiezen (als hij niet al gebruikt wordt), bijvoorbeeld: 'mijndomein.be'.
    • De workflowbeheerder (stap 2) kan het domein koppelen aan je bedrijf. Er kunnen meerdere domeinen worden gekoppeld. De beheerders van de Vlaamse Overheid moeten dit domein goedkeuren.
    • Zie Een domein beheren.
  • Stap 5: Toevoegen van een toepassing
    • De naam van de toepassing moet gelijk zijn aan de Common Name (CN) van je toepassing.
    • De aanvraag wordt vervolgens goedgekeurd door de workflowbeheerder.
    • Zie Een toepassing beheren.
  • Stap 6: Aanvragen van een certificaat
    • Vraag een certificaat aan met volgende gegevens:
      • Toepassing: kies de toepassing aangemaakt in stap 5
      • Type Certificaat: SSL Client
      • Geldigheidsduur: vrij te kiezen
      • CSR-bestand: upload het aangemaakte CSR-bestand

               

    • De aanvraag wordt goedgekeurd door een medewerker met de rol 'DCBaaS workflowbeheerder' (kan zelfde persoon zijn).
    • Het certificaat is nu actief en het CRT-bestand kan gedownload worden met de knop: .
    • Zie Een certificaat beheren

Certificaat hernieuwen

Certificaten vervallen na een bepaalde periode. Eén maand voor de vervaldatum wordt de contactpersoon verwittigd via e-mail.

Contacteer uw lokale beheerder of een gebruiker met de rol 'DCBaaS Certificatenbeheerder Organisatie'. Zij moeten een nieuw certificaat aanmaken via dcb.vlaanderen.be, dat in de toepassing het oude zal vervangen. Een certificaat hernieuwen is gelijkaardig aan de aanvraag van een nieuw certificaat. Een goede praktijk bij het hernieuwen van een certificaat is dat je een nieuw publiek/privaat sleutelpaar en een nieuwe CSR aanmaakt. Zie Een certificaat beheren onder de titel hernieuwen.

Starten met DOV-webservices

Met een certificaat (crt-bestand) en private sleutel (pem-bestand) kan je je authentificeren bij de DOV API. Vervolgens kan je requests uitvoeren en krijg je een response terug:

  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

Test het certificaat

Een certificaat kan eenvoudig getest worden met de request module van python.

Test eerst de connectie door een request te doen op chucknorris. Hier moet een geldig antwoord op komen zonder certificaat. Daarna een request uitvoeren waarvoor je alleen response krijgt met geldig certificaat.

Test Certificaat
import requests, os
os.environ['HTTP_PROXY']='proxy.vlaanderen.be:8080'
os.environ['HTTPS_PROXY']='proxy.vlaanderen.be:8080'

#certificaat
productie_key_pair = (<path to certificate>, <path to private key>)

#test connectie
requests.get('https://services.dov.vlaanderen.be/dovinstrumentserver/chucknorris').text

#test certificaat
requests.get('https://services.dov.vlaanderen.be/dovkernserver/actoren/0', cert=productie_key_pair).json()

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. Gebruikers op het netwerk van de Vlaamse overheid verlopen via 'proxy.vlaanderen.be:8080'. 

Voor de oefen omgeving kan 'services.dov.vlaanderen.be' vervangen worden door 'services-oefen.dov.vlaanderen.be'.

Quickstart

Python

Voorbeeldscripts voor het testen van certificaten, opvragen van instrument en sensor metadata, aanmaken en koppelen van instrumenten, en weergeven en opladen van meetpunten.

Java

Dit java quickstart-project demonstreert hoe je de DOV-services kan oproepen. Hoe je een secure connection opbouwt met een certificaat vind je hier.

Node.js

In hetzelfde quickstart-project vind je ook een voorbeeld in Node.js.

Voorbeelden

Data aanleveren door boorbedrijven

Zie pagina XML-bestanden aanleveren via DOV-webservices.

Data aanleveren voor grondwatermeetnet

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

  • No labels