Onderhoud Wegens upgrade omwille van een kritieke kwetsbaarheid zal confluence vandaag (18/12/2023) om 14u00 even onbeschikbaar zijn.
Informatie |
---|
Deze pagina werd gearchiveerd in 2023. Voor de meest recente versie, bekijk de bijgewerkte versie onder de tab 'Data aanleveren'. |
Inhoudsopgave | |
---|---|
Inhoudsopgave | |
outline | true | indent | p0px
Inleiding
DOV-services die we aanbieden op internet en waarvoor authenticatie nodig is, worden standaard beveiligd met certificaten. We gebruiken hiervoor standaard de VO-PKI.
...
- 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 bijvoobeeld 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.
...
- Aanvraag toegang DOV-services
- Aanmaken certificaat
...
Stap 1. Aanvraag tot toegang tot DOV-services
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-services
- 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) registreren bij het VO Digitaal Certificaten Beheer opstellen en daaraan de nodige rechten toekennen tot de DOV-applicaties. Vervolgens zal DOV deze CN terugsturen. De CN 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.
Informatie |
---|
Sinds 01/03/2021 is het nieuw Certificatenbeheer (Vo-DCBaaS) gelanceerd en dient werk gemaakt te worden van migratie bestaande certificaten. Meer info op |
...
...
Stap 1 - Lokaal beheerder binnen uw organisatie
...
nieuws/lancering-nieuw-certificatenbeheer-vo-dcbaas-en-migratie-bestaande-certificaten De werking van Certificatenbeheer staat hier beschreven: https://overheid.vlaanderen.be/ |
...
...
...
...
...
...
...
...
...
...
Stap 2 - Verlenen van toegang aan certificaatbeheerder
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.
Stap 3 - Aanmaak CSR-bestand
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.
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.
Stap 2.1 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'
Stap 2.2 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
de lokale beheerder kan gebruikersrechten toekennen via gebruikersbeheer.vlaanderen.be
Gebruik maken van DOV-services
Hoe je het certificaat kan testen en je het gebruikt om de DOV-services aan te spreken, lees je op Algemeen: aanspreken van de DOV-webservices
Codeblok | ||
---|---|---|
| ||
openssl req -out CSR.csr -new -newkey rsa:2048 -keyout privatekey.key |
...
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)
- er zijn online websites die een csr / private key pair kunnen genereren, bvb https://csrgenerator.com/ of https://www.https.in/support/csr-generation .
Voor elke van deze komt een popop met de CSR en private key samen; sla deze op in verschillende bestanden
Het resultaat: 2 bestanden die er zo uitzien:
Codeblok | ||||
---|---|---|---|---|
| ||||
-----BEGIN CERTIFICATE REQUEST-----
MIICuzCCAa..................................
-----END CERTIFICATE REQUEST----- |
Codeblok | ||||
---|---|---|---|---|
| ||||
-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIFHDBOBgk..............
-----END ENCRYPTED PRIVATE KEY----- |
Waarschuwing |
---|
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. |
Stap 4 - Downloaden certificaat
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.
Aanspreken DOV-services
Met een getekend certificaat kan men requests uitvoeren tegen de DOV REST API. Hiervoor dient volgend stappenplan gevolgd te worden:
- Definieer een HTTPS-connectie gebruikmakend van uw certificaat
- Stuur het request naar https://services.dov.vlaanderen.be/[APP]/[REST], waarbij
- APP de applicatienaam in DOV is die men wenst aan te spreken
- 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 command te gebruiken:
Codeblok | ||||
---|---|---|---|---|
| ||||
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:
...