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:

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

1. Maak een nieuw project aan via “File > New SOAP project”
   
   
   

2. Kies een naar voor het project
   
   
3. In “Initial WSDL” kies het .wsdl bestand dat werd aangeleverd voor de MAGDA webdienst waarvoor u het certificaat wenst te gebruiken.
4. 'OK'

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

1. Open “Project View” van het aangemaakte project:
   
   

2. Ga naar WS-Security Configuration > Keystores en voeg een keystore toe:
   
   
   

3. Kies de aangemaakte keystore en geef het keystore wachtwoord in:
   
   
   
4. Bij een correct wachtwoord verschijnt er OK onder “Status”
   

3.Configureer WS-security

1. Maak een nieuwe “Outgoing WS-Security Configuration”:
   

2. Kies een naam:
   
   

3. Maak een nieuw onderdeel onder deze configuratie
   
   
   

4. Kies “Signature” als type:
   
   

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

1. Open de algemene preferences van SoapUI
   
   
   

2. Kies opnieuw de aangemaakt JKS keystore, en vul het wachtwoord in:
   

5.Bouw een geldige request

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

1. Vul de juiste URL in het vak bovenaan. De endpoint hebt u gekregen tijdens het aansluitingsproces.
   Voorbeeld voor e-invoice:
   
   

2. Open het autorisatie-blad
   
   

3. Maak een nieuwe autorisatie (klik op Auth) om beveiliging in te stellen op berichtniveau (WS security). 
   
   
   

4. Kies type “Basic”:
   
   
   

5. Kies de aangemaakt WSS configuratie bij “Outgoing WSS”:
   
   

6. Indien de lijst leeg is, sluit het request-venster en open het opnieuw.

7.Uitvoeren

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

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.