In het kader van de nieuwe VO-DCBaas toepassing, heb je nieuwe certificaten nodig (zie ook documentatie rond de migratie) – het is hierbij belangrijk dat het nieuwe certificaat zowel voor de digitale handtekening van de request als voor het tekenen van de SSL verbinding gebruikt wordt. Een combinatie van een ‘oud’ en een ‘nieuw’ certificaat is namelijk niet toegelaten.

Nodige tools

OpenSSL is nodig om met private keys en certificaten te werken.
https://www.openssl.org/
XCA is nodig om een Java keystore aan te maken.
Koppelen van de Private Key en het certificaat
Keystore Explorer om van een PKCS12 file naar een JKS file te gaan. https://keystore-explorer.org/downloads.html
SoapUI is nodig om requests naar MAGDA-VSB uit te voeren.
http://www.soapui.org/
- De gratis versie is voldoende.
- Onderstaande instructies gelden voor versie 5. Oudere versies hebben wat verschillen qua UI.
- Bij gebruik van een forward proxy is het mogelijk dat er problemen zijn met recente versies. In dit geval, probeer SoapUI 4.0.1 (enkel de pro versie is nog te downloaden – zonder licentie werkt het zoals de gratis versie)

Controleer het certificaat

Controleer het certificaat dat u ontvangt van certificatenbeheer, let vooral op dat de CN correct is en overeenkomt met de ontvangen parameters van het MAGDA Aansluitingsteam.

Voorbeeld voor VDAB:

$ openssl x509 -text -noout –inform der -in certificate.der

Certificate:

Data:

Version: 3 (0x2)

Serial Number:

54:a5:e8:70:00:00:00:00:00:97

Signature Algorithm: sha1WithRSAEncryption

Issuer: C=BE, O=e-IB (DAB ICT), CN=Vlaamse overheid Issuing CA 2

Validity

Not Before: Jul 17 07:44:58 2014 GMT

Not After : Aug 20 07:44:58 2019 GMT

Subject: C=BE, ST=Brussel, L=Brussel, O=BELVPOVO0000780, OU=VDAB, CN=wse.vlaanderen.be/vdab/einvoicing-test/emailAddress=licenties@vdab.be

(…)

*.vlaanderen.be

Indien uw toepassing een connectie maakt naar een .vlaanderen.be of .vonet.be -URL zoals de MAGDA diensten dient u om problemen in de toekomst te vermijden best het Globalsign certificaat vertrouwen. Het .vlaanderen.be of .vonet.be is immers een certificaat dat om de zoveel tijd dient hernieuwd te worden. Als het vervangen wordt door een nieuw dan loopt u het risico dat u de toegang tot de MAGDA diensten zal geweigerd worden.

Toepassingen die enkel elementen uit de huidige certificate chain vertrouwen (bvb. het certificaat zelf, het intermediate of het root certificaat) kunnen dus potentieel wel problemen ondervinden.

Dit root certificate kan u terugvinden op https://support.globalsign.com/ca-certificates/root-certificates/globalsign-root-certificates en is het R3 GlobalSign Root Certificate.

GlobalSign Root R3
SHA256 • RSA • 2048

Valid until: 18 March 2029
Serial #: 04:00:00:00:00:01:21:58:53:08:a2
Thumbprint: d6:9b:56:11:48:f0:1c:77:c5:45:78:c1:09:26:df:5b:85:69:76:ad

Gebruik in SoapUI

In 'Koppelen van de Private Key en het certificaat' wordt een sleutelkastje (keystore – JKS) aangemaakt die een private key bevat en een certificaat aangemaakt in certificatenbeheer. Deze keystore wordt in deze handleiding gebruikt om een SOAP project op te zetten.

1. Maak een nieuw project

Maak een nieuw project aan via “File > New SOAP project”
Kies een naar voor het project
In “Initial WSDL” kies het .wsdl bestand dat werd aangeleverd voor de MAGDA webdienst waarvoor u het certificaat wenst te gebruiken.
'OK'
SoapUI toont de dienst met zijn operaties:

2. Zet je PKCS12 file om naar een JKS file
Wanneer je de handleiding op https://assets.vlaanderen.be/image/upload/v1628695506/Handleiding_CSR_sf7f0q.pdf puntje 3.6 hebt
uitgevoerd heb je nu een certificaat in pkcs12 formaat. Dit is helaas niet bruikbaar in Soap UI. Daarom moet je eerst dit bestand omzetten
naar een .jks formaat.

1. Open Keystore explorer
2. Selecteer File > Open
3. Ga naar je PKCS12 file dat je wil laten omzetten naar een JKS file
4. Klik Open
5. Keystore Explorer zal vragen om die keystore te unlocked. Klik op Unlock Keystore, geef je paswoord in en klik op OK

6. Selecteer File > Save As
7. Geef de .jks file een naam en zet er zeker de extensie .jks bij
8. Klik op Save
9. Nu moet je die file ook nog echt een jks formaat geven. Dit doe je door te klikken op Tools > Change Type > JKS.

10. Je zal je paswoord nog eens moeten ingeven maar dan krijg je de melding "Change Keystore type Succesfull"
11. Klik nog eens op File > Save
Nu is je Keystore opgeslagen in JKS formaat.

3. Configureer keystore

Open “Project View” van het aangemaakte project:
Ga naar WS-Security Configuration > Keystores en voeg een keystore toe:
Kies de aangemaakte keystore en geef het keystore wachtwoord in:
Bij een correct wachtwoord verschijnt er OK onder “Status”

3.Configureer WS-security

Maak een nieuwe “Outgoing WS-Security Configuration”:
Kies een naam:
Maak een nieuw onderdeel onder deze configuratie
Kies “Signature” als type:
Configureer de signatuur:
- Keystore: de keystore entry die net in SoapUI aangemaakt is
- Alias: kies de alias van de private key uit de lijst
- Password: het wachtwoord van de private key
- Key Identifier Type: “Binary Security Token”
- Signature Algorithm: zie screenshot
- Signature Canonicalization: zie screenshot
- Digest Algorithm: zie screenshot
- Use Single Certificate: Nee
- Parts: geen

6. Sluit het “Project View” venster.

4.Configureer SSL

Open de algemene preferences van SoapUI
Kies opnieuw de aangemaakt JKS keystore, en vul het wachtwoord in:

5.Bouw een geldige request

Open voor de gewenste operatie de gegenereerde request en pas die aan.

De geldigheid van de request kan gecontroleerd worden met Alt-V. Er mogen geen validatiefouten zijn.

6.Configureer de request

Vul de juiste URL in het vak bovenaan. De endpoint hebt u gekregen tijdens het aansluitingsproces.
Voorbeeld voor e-invoice:
Open het autorisatie-blad
Maak een nieuwe autorisatie (klik op Auth) om beveiliging in te stellen op berichtniveau (WS security).
Kies type “Basic”:
Kies de aangemaakt WSS configuratie bij “Outgoing WSS”:
Indien de lijst leeg is, sluit het request-venster en open het opnieuw.

7.Uitvoeren

Klik op de groene 'play' knop naast de URL

Als u nog nog geen communicatie ontvangen hebt van het MAGDA-team Aansluitingen dat uw diensten geconfigureerd werden in T&I of Productie zult u geen volledige bevraging kunnen doen van de dienst. U zult in dat geval 'geen machtiging' ontvangen als foutmelding, dit betekent dat uw tot aan de dienst komt maar er geen configuratie gevonden is. Indien u andere foutmeldingen krijgt kunt u hieronder kijken naar veel voorkomende fouten.

voor E-invoice

OPGELET: indien u uw certificaat gebruikt om een beveiligde connectie op te zetten over het MAGDA-platform naar het federale Mercurius platform (achter de FSB, de federale service bus) om daar e-facturen op te halen, dan bent u succesvol als u uiteindelijk een foutmelding terugkrijgt.

Als u de foutmelding “Internal Server Error (Unauthorized Access)” krijgt betekent dit dat u succesvol tot aan het Mercurius platform geraakt bent, maar dat daarop nog niet uw inbox met e-facturen opgezet werd. Contacteer de MAGDA Service Desk voor de verdere opzet van de e-invoicing toegang.

Troubleshooting

Controleer altijd de SoapUI logs om zeker te zijn dat er geen foutmeldingen aanwezig zijn.

SoapUI: Connection failed

Indien er een proxy nodig is, configureer in die Properties > Proxy. Indien er dan een SSLPeerUnverifiedException gegeven wordt, kan het zijn dat er problemen zijn met de recente versie van SoapUI. Probeer dan te testen met SoapUI 4.0.1

ERR_*

De reverse proxy van de Vlaamse overheid aanvaardt de request niet. Mogelijke oorzaken:

Certificaat niet gekend
- Controleer of u de juiste CN gebruikt hebt in de CSR, deze is hoofdlettergevoelig en kan verschillen van de URI
- Controleer of u de juiste URI gebruikt bij identificatie afzender, deze is hoofdlettergevoelig en kan verschillen van de CN
- Contacteer de MAGDA Service Desk.
Geen signature gevonden
- Controleer alle stappen opnieuw
Certificaat CN komt niet overeen met de ApplicationID in de SOAP header
- Wijzig ApplicationID zodat ze wel overeenkomen

In onderstaande flowchart kunt u de mogelijk oorzaak van de foutmelding opzoeken

VSB-*

Het MAGDA-VSB platform aanvaardt de request niet.
Contacteer de Kruispuntbank Vlaanderen Service Desk.

In deze handleiding

Andere handleidingen

Handleiding voor gebruikers .Net

Browser not supported