Je bekijkt een oude versie van deze pagina. Bekijk de huidige versie.

Vergelijk met huidige Toon pagina historie

« Vorige Versie 6 Volgende »

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.

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 bijvoobeeld uw eigen flow wil testen zonder de productiedata te beïnvloeden, dient u hiervoor ook een afzonderlijk certificaat te gebruiken


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

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

Aanmaken certificaat

Het aanmaken van een certificaat is een actie die integraal door de aanvrager kan gerealiseerd worden.

Stap 1 - Lokaal beheerder binnen uw organisatie

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

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 aan. De inhoud van de CSR moet exact overeenkomen met de aangevraagde CN. Dit is de volledige verantwoordelijkheid van de aanvrager.

U kan gebruik maken van bestaande tools voor de aanmaak van CSR, bv. https://www.sslshopper.com/csr-decoder.html

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:

  1. Definieer een HTTPS-connectie gebruikmakend van uw certificaat
  2. Stuur het request naar https://services.dov.vlaanderen.be/[APP]/[REST], waarbij 
    1. APP de applicatienaam in DOV is die men 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 command 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

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:

  • Geen labels