DOV-services die we aanbieden op internet en waarvoor authenticatie nodig is, worden standaard beveiligd met certificaten. We gebruiken hiervoor standaard de VO-PKI.
We hanteren de regel 1 certificaat per unieke combinatie organisatie-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:
DOV zal vervolgens een 'Common Name' (CN) registreren bij het VO Digitaal Certificaten Beheer en daaraan de nodige rechten toekennen tot de DOV-applicaties. Vervolgens zal DOV deze CN terugsturen. De CN is zeer belangrijk bij het aanmaken van het certificaat.
Het aanmaken van een certificaat is een actie die integraal door de aanvrager kan gerealiseerd worden.
Achtergrondinformatie: https://overheid.vlaanderen.be/certificatendienst-vlaamse-overheid
U dient ervoor te zorgen dat er binnen uw organisatie een 'Lokale beheerder' beschikbaar is binnen het gebruikersbeheer van de Vlaamse Overheid. Volg daarvoor de stappen zoals vermeld op https://overheid.vlaanderen.be/doelgroep-gebruikersbeheer#wie-kan-het-gebruikersbeheer-van-de-vlaamse-overheid-gebruiken-om-gebruikers-en-rechten-te-beheren
De lokale beheerder van de betrokken entiteit moet toegang verlenen tot de aangemaakte CNs in het gebruikersbeheer aan één of meerdere van zijn medewerkers die de certificaten zullen aanvragen. Indien de lokale beheerder zelf deze verantwoordelijkheid opneemt, moet deze zichzelf de nodige rechten toekennen.
Het verlenen van toegang kan via https://vo-gebruikersbeheer.vlaanderen.be/
Onderstaande screenshots geven weer welke elementen ingevuld dienen te worden. Het type certificaat zal altijd 'SSL Client' zijn.
Vervolgens maakt u lokaal een CSR (Certificate Signing Request) bestand en bijhorende private key aan. De inhoud van de CSR moet exact overeenkomen met de aangevraagde CN. Dit is de verantwoordelijkheid van de aanvrager.
De private key is nodig om later het certificaat te kunnen gebruiken.
Er zijn veel methodes om een CSR aan te maken, we sommen er maar enkele op:
openssl - dit is een (opensource) command line tool die standaard op vele Operating systemen beschikbaar is.
openssl req -out CSR.csr -new -newkey rsa:2048 -keyout privatekey.key |
Nu moeten enkele gegeven ingevuld worden. Voor DOV is enkel de 'Common Name' van belang - vul de andere velden wel waarheidsgetrouw in.
De aanmaak van een CSR wordt hier gedemonstreerd.
(voor windows gebruikers is dit helaas geen standaard tool, maar is te downloaden https://slproweb.com/products/Win32OpenSSL.html)
Het resultaat: 2 bestanden die er zo uitzien:
-----BEGIN CERTIFICATE REQUEST----- MIICuzCCAa.................................. -----END CERTIFICATE REQUEST----- |
-----BEGIN ENCRYPTED PRIVATE KEY----- MIIFHDBOBgk.............. -----END ENCRYPTED PRIVATE KEY----- |
Indien om één of andere reden de private key verloren raakt is er geen mogelijkheid om deze te recupereren. Op dat moment is het certificaat onbruikbaar en moet alles vanaf stap 3 opnieuw volledig doorlopen worden. |
De personen die in stap 2 de nodige rechten gekregen hebben, kunnen nu met behulp van de CSR die in stap 3 aangemaakt is een certificaat aanvragen & downloaden.
Het aanvragen en downloaden kan via https://certificatenbeheer.vlaanderen.be
Onderstaande screenshots geven aan welke info u dient in te vullen en hoe u het certicaat kan downloaden.
Met een getekend certificaat kan men requests uitvoeren tegen de DOV REST API. Hiervoor dient volgend stappenplan gevolgd te worden:
Testen van certificaat
De eenvoudigste manier om een certificaat te testen is om een curl command 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 |
Voor de oefen omgeving kan de url https://services.dov.vlaanderen.be/dov-xdov-server/logs/count gebruikt worden
Voor java ontwikkelaars
Er is een java quickstart project beschikbaar die demonstreert hoe de services opgeroepen kunnen worden: https://github.com/DOV-Vlaanderen/dov-services-quickstart gemaakt
Heel specifiek, alles wat betreft het opbouwen van een secure connection met een certificaat staat in https://github.com/DOV-Vlaanderen/dov-services-quickstart/blob/master/config/src/main/java/be/vlaanderen/dov/services/config/ClientConfig.java
Voor python ontwikkelaars
Hier is nog geen voorbeeldcode beschikbaar.
De beschrijving zoals bvb op https://www.techcoil.com/blog/how-to-send-a-http-request-with-client-certificate-private-key-password-secret-in-python-3/ gegeven wordt kan gevolgd worden
In de subpagina's worden enkele voorbeelden aangehaald voor het gebruik van DOV REST API: