Hoe importeer je een SSL-certificaat in MKG?

Verlenging van een standaard SSL-certificaat

Een commercieel SSL-certificaat heeft een bepaalde geldigheid van ongeveer 1 jaar. Om gebruik te kunnen blijven maken van o.a. de Shop Floor, moet deze tijdig worden verlengd bij een SSL-leverancier/certificaatautoriteit. Deze verantwoordelijkheid ligt bij de klant. In de meeste gevallen wordt hiervoor de IT-partij ingeschakeld door de klant.

Voor het verlengen óf voor een heruitgifte van een bestaand SSL-certificaat heb je, afhankelijk van je SSL-leverancier, opnieuw het oorspronkelijke CSR (Certificate Signing Request)-bestand nodig. Het CSR-bestand (mkgapi.<domeinnaam>.csr) kun je terugvinden in de \apps\mkg_pas\conf map op de MKG server. Mocht je het daar niet meer terugvinden, dan is het mogelijk om deze via onderstaande stappen opnieuw te genereren.  

1. Start een MKG client en log in als beheerder of als een gebruiker met beheerdersrechten.
2. Kies in de module Systeemanalyse voor de actie Genereer initieel CSR bestand opnieuw. Geef de gegevens in die van toepassing zijn op jouw organisatie en klik op OK. (Indien deze module niet in je menu staat dan kan je deze oproepen door rechtsboven in het zoekveld systeemanalyse op te zoeken..)
3. De gegenereerde CSR-output wordt in een pop-up getoond. Tevens wordt het aangemaakte CSR-bestand weggeschreven naar de map \apps\mkg_pas\conf op de MKG server.

Een standaard SSL-certificaat importeren

Het importeren kan op verschillende manieren die hieronder worden beschreven. Kies de methode die het beste aansluit bij je situatie:

1. Java keytool: commandline, géén MKG-account nodig, vereist een certificaatbundel (root, intermediate, enduser).
2. MKG client: via de GUI van MKG, MKG account noodzakelijk, vereist een certificaatbundel (root, intermediate, enduser).
3. KeyStore Explorer: open source tool met GUI, géén MKG-account vereist. Deze methode biedt de meeste mogelijkheden, kan bijvoorbeeld overweg met .PFX, en .P12 bestanden en je kunt hiermee tevens nieuwe Java KeyStore(s) genereren. 

Methode Java Keytool

1. Maak een nieuw .txt bestand aan en plak hier volgordelijk het root-, intermediate en end-user certificaat in welke verkregen is uit het certificaatbundel bestand. Het .txt bestand moet uit 3 blokken bestaan:

   -----BEGIN CERTIFICATE-----
   ROOT CERT
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   INTERMEDIATE CERT
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   END-USER CERT
   -----END CERTIFICATE-----
   

2. Hernoem het *.txt bestand naar new_certificate.crt. Deze bevat nu de gehele certificaten chain.
3. Maak een backup van de bestaande keystore (*.jks bestand) in \\apps\mkg_pas\conf.
4. Open een Command prompt (elevated) en ga naar \\apps\dlc1176\jdk\bin\
5. Voer het volgende commando uit:

   keytool -import -trustcacerts -alias mkgapi -file new_certificate.crt -keystore je_huidige_keystore.jks

6. Er wordt gevraagd naar het keystore password. 
   • Keystore password is terug te vinden in het bestand \\apps\mkg_pas\conf\catalina.properties onder psc.as.https.keypass
   • Alias is tevens terug te vinden in het catalina.properties bestand onder psc.as.https.keyalias
7. Indien het certificaat juist kon worden geïmporteerd, volgt de volgende melding: Certificate reply was installed in keystore
8. Herstart de 'MKG Application server' service om de bijgewerkte keystore te effectueren.

Methode KeyStore Explorer

Benodigdheden: KeyStore Explorer (open source).
Download link: https://keystore-explorer.org/downloads.html  (inclusief Java runtime)

Voorinformatie: MKG werkt met een Java KeyStore (kluis). Om een (nieuwe) Java KeyStore te genereren is het volgende nodig:

• Private key en end user certificaat
• Root en intermediate certificaat

Wanneer je geen private key hebt, kun je deze exporteren uit een bestaande Java KeyStore of een PFX bundel. Dit gaat als volgt:

1. Open Keystore Explorer.
2. Open de bestaande JKS (Java keystore kluis) of P12 of PFX.

NB. Passcode kan in geval van een JKS teruggevonden worden in het catalina.properties bestand. (\apps\mkg_pas\conf)

3. Klik op het certificaat > rechtermuisknop > Export > Export Private Key. Er wordt wederom om het keystore password gevraagd.
4. Kies voor OpenSSL als type.
5. Vink Encrypt UIT en klik op Export.

Exporteer klant, intermediate en root certificaat:

6. Klik op het certificaat > rechtermuisknop > View Details > Certificate Chain Details
7. Exporteer voor ieder van de 3 regels (root, intermediate en klant) het certificaat door deze aan te klikken en op Export te klikken.

Genereer een nieuwe Java KeyStore:

1. Kies voor New > JKS
2. Rechtermuisknop > Import Key Pair
3. Kies voor OpenSSL
4. Vink Encrypted Private Key UIT.
5. Selecteer het OpenSSL Private Key file en bij Certificate File het Klant certificaat en klik op Import.
6. Voer bij Enter Alias ‘mkgapi’ in.

NB. mkgapi is het standaard alias. Dit kan soms afwijken. Wanneer de ingevoerde alias afwijkt van de wamkgapiarde die gevuld is in het catalina.properties bestand geeft Tomcat naderhand bij het starten een fout.

7. Voer bij Enter New Password én het password in wat gevonden kan worden in het catalina.properties bestand. De regel begint met: psc.as.https.keypass.
8. Klik op het certificaat > rechtermuisknop > Edit Certificate Chain > Append Certificate. Kies het intermediate certificaat.

NB. Indien er een mismatch ontstaat, is er het verkeerde certificaat gekozen. Kies dan het andere bestand.

9. Herhaal stap 13 en kies nu het root certificaat.
10. Kies voor File > Save KeyStore As en sla deze op als *.JKS.
11. Maak tijdelijk een kopie aan van het huidige mkgapi_<domeinnaam>.JKS bestand in de \\apps\mkg_pas\conf folder.
12. Vervang het huidige JKS bestand met het nieuwe JKS bestand.
13. Herstart de MKG Application service (=webserver).
14.  

Methode via MKG client

1. Start een MKG client en log in als beheerder of als een gebruiker met beheerdersrechten.
2. Kies in de module Systeemanalyse voor de actie Importeer standaard SSL certificaat.
3. Selecteer het 'root, intermediate en end-user'-certificaat (*.cer of *.crt) en vul de rest van de gegevens in inclusief het keystore wachtwoord en klik op OK. Er verschijnt een melding dat het SSL-certificaat succesvol is geïmporteerd.
4. Herstart de 'MKG Application server' service om de bijgewerkte keystore te effectueren.

5. Controleer of het SSL-certificaat met succes is verlengd. Dit kan op verschillende manieren:
   • Ga in een MKG client naar Help
     » MKG API… » Tabblad 'Beheer' » SSL verloopdatum.
   • Open een willekeurige browser. Ga naar en controleer via 'https://[domein]:[poort]/mkgbridge' de verloopdatum van het certificaat.

Zijn het domein en/of het poortnummer niet bekend? Het domein kan teruggevonden worden in het bestand \apps\mkg_pas\conf\server.xml op de MKG server (zie tag 'Keystorefile'). Het poortnummer is terug te vinden in het bestand \apps\mkg_pas\conf\catalina.properties (zie tag 'psc.as.https.port').

Troubleshooting

Indien de SSL-verloopdatum niet is bijgewerkt, controleer dan of de keystore kluis op de server is bijgewerkt met de date/timestamp van vandaag. Het .jks-bestand kun je vinden in de map \apps\mkg_pas\conf op de MKG server. Indien deze niet is bijgewerkt, kunnen er twee zaken aan de hand zijn:

• Voor het verlengen/heruitgifte van het SSL-certificaat is een afwijkende CSR gebruikt. Hierdoor komt de private key van de keystore kluis niet overeen met het vernieuwde SSL-certificaat. Controleer nogmaals of je bij het verlengen het juiste CSR-bestand hebt gebruikt. Voer de stappen vanaf stap 3 opnieuw uit.
• Tijdens het importeren is een foutief keystore wachtwoord gebruikt. Controleer of het ingevoerde wachtwoord overeenkomt met het wachtwoord in het bestand \apps\mkg_pas\conf catalina.properties op de MKG server (zie tag 'psc.as.https.keypass'). Probeer het SSL-certificaat opnieuw te importeren.

Indien het .jks-bestand wel is bijgewerkt en je de MKG Application server reeds hebt herstart, kan het in sommige gevallen nodig zijn om ook de MKG server te herstarten.

Een *wildcard SSL-certificaat importeren

Wildcard SSL-certificaten kunnen voor meerdere domeinnamen gebruikt worden. CSR-bestanden die nodig zijn voor het aanvragen van wildcard SSL-certificaten, worden vaak op andere plekken gegenereerd, bijvoorbeeld op een domain controller. De keystore kluis bevindt zich veelal ook op een andere (centrale) plek binnen het serverpark.

Voor het importeren van een wildcard SSL-certificaat heb je onder andere het 'root, intermediate en end-user' (client)-certificaat nodig inclusief private key.

Stappenplan

1. Start een MKG client en log in als beheerder of als een gebruiker met beheerdersrechten.
2. Kies in de module Systeemanalyse voor de actie Importeer wildcard SSL certificaat.
3. Selecteer het root, intermediate en end-user certificaat (*.cer of *.crt), de private key file en vul de rest van de gegevens in inclusief het keystore wachtwoord en klik op OK. Er verschijnt een melding dat het SSL-certificaat succesvol is geïmporteerd.
4. Herstart de 'MKG Application server' service.

5. Controleer of het SSL-certificaat met succes is verlengd. Dit kan op verschillende manieren:
   • Ga in een MKG client naar Help
     » MKG API… » Tabblad 'Beheer' » SSL verloopdatum.
   • Open een willekeurige browser. Ga naar en controleer via 'https://[domein]:[poort]/mkgbridge' de verloopdatum van het certificaat.

Zijn het domein en/of het poortnummer niet bekend? Het domein kan teruggevonden worden in het bestand \apps\mkg_pas\conf\server.xml op de MKG server (zie tag 'Keystorefile'). Het poortnummer is terug te vinden in het bestand \apps\mkg_pas\conf\catalina.properties (zie tag 'psc.as.https.port').

Troubleshooting

Indien de SSL-verloopdatum niet is bijgewerkt, controleer dan of de keystore kluis op de server is bijgewerkt met de date/timestamp van vandaag. Het .jks-bestand kun je vinden in de map \apps\mkg_pas\conf op de MKG server. Indien deze niet is bijgewerkt, kunnen er twee zaken aan de hand zijn:

• Voor het verlengen/heruitgifte van het SSL-certificaat is een afwijkende CSR gebruikt. Hierdoor komt de private key van de keystore kluis niet overeen met die van het vernieuwde SSL certificaat. Controleer nogmaals of je bij het verlengen de juiste CSR bestand hebt gebruikt. Voer de stappen vanaf stap 3 opnieuw uit.
• Tijdens het importeren is een verkeerd keystore wachtwoord gebruikt. Controleer of het ingevoerde wachtwoord overeenkomt met het wachtwoord in het bestand \apps\mkg_pas\conf catalina.properties op de MKG server (zie tag 'psc.as.https.keypass'). Probeer het SSL-certificaat opnieuw te importeren.

Indien het .jks-bestand wel is bijgewerkt en je de MKG Application server reeds hebt herstart, kan het in sommige gevallen nodig zijn om ook de MKG server te herstarten.

Een nieuw standaard SSL-certificaat aanvragen

Het aanvragen van een nieuw standaard SSL-certificaat is enkel van toepassing bij een nieuwe installatie van MKG, waarbij er nog niet eerder met een SSL-certificaat gewerkt is. Normaal gesproken vallen onder de opstart/installatie werkzaamheden die door een technisch consultant van MKG in overleg met de klant worden uitgevoerd.

Stappenplan

1. Start een MKG client en log in als beheerder of als een gebruiker met beheerdersrechten.
2. Kies in de module Systeemanalyse voor de actie Genereer nieuw CSR bestand (ten behoeve van aanvragen initieel SSL-certificaat). Geef vervolgens de gegevens in die van toepassing zijn op jouw organisatie:
   • Algemene naam. mkgapi.uwbedrijfsnaam.nl. De domeinnaam uwbedrijfsnaam.nl dient in je bezit te zijn. Daarnaast is het noodzakelijk om voor dit domein DNS records aan te kunnen passen.
   • Bedrijfsnaam. Bedrijfsnaam B.V. Geef de volledige bedrijfsnaam in, zoals deze bekend is bij de instanties. Afhankelijk van het type certificaat dat aangeschaft wordt, dient deze exact overeen te komen.
   • Afdeling. IT.
   • Plaats. Geef de vestigingsplaats in, zoals deze bekend is bij de instanties. Afhankelijk van het type certificaat dat aangeschaft wordt, dient dit overeen te komen.
   • Provincie. Geef de provincie in waarin bovenstaande plaats zich bevindt.
   • Land. Geef de tweeletterige landcode in volgens de ISO 3166-1 standaard.
   • Keystore wachtwoord. Vul hier een sterk wachtwoord in van minimaal 6 tekens. Gebruik enkel alfanumerieke tekens (letters + cijfers). Het wachtwoord zal bij het installeren van het aangevraagde certificaat weer nodig zijn; bewaar dit dus goed!
   • Alias. Het is gebruikelijk om hier het eerste gedeelte van de 'Algemene naam' in te vullen. Het alias zal bij het installeren van het aangevraagde certificaat weer nodig zijn; bewaar ook dit dus goed!
3. Klik vervolgens op OK.
4. De gegenereerde CSR-output wordt in een pop-up getoond. Tevens wordt het aangemaakt CSR-bestand weggeschreven naar de map \apps\mkg_pas\conf op de MKG server. Als laatste wordt er een SSL-keystore kluis aangemaakt, waarin het nieuwe certificaat kan worden geïmporteerd.
5. Gebruik de CSR om een nieuw SSL-certificaat aan te vragen bij je certificaatautoriteit.

Wanneer je het SSL-certificaat met succes hebt kunnen aanvragen ontvang je een certificaatbundel van je certificaatautoriteit. Deze bevat onder andere het 'root, intermediate en end-user' (client)-certificaat. De volgende stap is om deze te importeren.

Aanvullende netwerk-/systeeminstellingen

De MKG API is bedoeld om externe applicaties of diensten, zoals de MKG App of de MKG API-Toolbox, te verbinden met de MKG-omgeving. Met de voorgaande stappen heb je de voorbereidingen getroffen om het dataverkeer te beveiligen met behulp van een SSL-certificaat. Voor het ontsluiten van de functionaliteit buiten de MKG applicatieserver of het interne bedrijfsnetwerk is het nodig dat de volgende stappen worden toegepast.

Pas firewallregels toe

De MKG API maakt gebruikt van een Apache Tomcat®-instance, waarbij de connector is ingesteld om op poort 443 TCP te luisteren. Mochten er onverhoopt andere services actief zijn die ook van deze poort gebruikmaken, dan kan dit gewijzigd worden in het bestand \apps\mkg_pas\conf\catalina.properties op de MKG server (zie tag 'psc.as.https.port').

Firewallregel op applicatieserver

De firewall die actief is op de MKG applicatieserver, dient opengesteld te worden voor verkeer op poort 443 TCP. Desgewenst kan het verkeer enkel worden gekoppeld of toegestaan voor de Tomcat®-instance (bestand \apps\dlc1176\servers\pasoe\bin\tomcat8.exe).

Firewallregel WAN > LAN

De firewall die de internetverbinding scheidt van het interne netwerk, dient tevens een openstelling alsook een forwarding te hebben naar de MKG server. Een voorbeeldregel:

• Destination host: ip-adres van de MKG server
• Source host: ALL
• Inbound port: 443 (zolang de poort in de Tomcat®-instance niet is aangepast)
• Outbound port: 443 (als deze reeds in gebruik is, dan is 7443, 8443 of 9443 een alternatief)
• Data mode: TCP

Pas een DNS-record toe

Om verbinding te kunnen maken met de MKG API is een DNS-record nodig. Hierbij wordt een naam, zoals 'mkgapi.uwbedrijfsnaam.nl', omgezet naar een internetadres (het WAN ip-adres van het bedrijfsnetwerk), zoals '8.8.8.8'. Bij het toepassen van SSL-certificaten is het eigenlijk standaard om een naam toe te passen. Het toevoegen of aanpassen van dergelijke records dient bij de partij te gebeuren waar de domeinnaam is ondergebracht.

Troubleshooting

Indien de SSL-verloopdatum niet is bijgewerkt, controleer dan of de keystore kluis op de server is bijgewerkt met de date/timestamp van vandaag. Het .jks-bestand kun je vinden in de map \apps\mkg_pas\conf op de MKG server. Indien deze niet is bijgewerkt, kunnen er twee zaken aan de hand zijn:

• Voor het verlengen/heruitgifte van het SSL-certificaat is een afwijkende CSR gebruikt. Hierdoor komt de private key van de keystore kluis niet overeen met die van het vernieuwde SSL-certificaat. Controleer nogmaals of je bij het verlengen de juiste CSR bestand hebt gebruikt.
• Tijdens het importeren is een verkeerde keystore wachtwoord gebruikt. Controleer of het ingevoerde wachtwoord overeenkomt met het wachtwoord in het bestand \apps\mkg_pas\conf catalina.properties op de MKG server (zie tag 'psc.as.https.keypass'). Probeer het SSL-certificaat opnieuw te importeren.

Indien het .jks-bestand wel is bijgewerkt en je de MKG Application server reeds hebt herstart kan het in sommige gevallen nodig zijn om ook de MKG server te herstarten.

Bereikbaarheid in browser controleren

• Interne test. Start op de applicatieserver een browsersessie (bijvoorbeeld in Google Chrome of Mozilla Firefox) naar 'https://localhost/mkg' (of naar 'https://localhost/mkg:7443'. Wanneer er een pagina wordt weergegeven met de tekst "REST adapter", betekent dit dat de service actief is binnen het eigen bedrijfsnetwerk.
• Externe test. Start op een werkplek een browsersessie (bijvoorbeeld in Google Chrome of Mozilla Firefox) naar 'https://mkgapi.uwbedrijfsnaam.nl/mkg' (of naar 'https://mkgapi.uwbedrijfsnaam.nl:7443/mkg'. Wanneer er een pagina wordt weergegeven met de tekst "REST adapter", betekent dit dat de service actief is buiten het eigen bedrijfsnetwerk en dat de technische inrichting juist is uitgevoerd. Is dit niet het geval, dan is de inrichting niet uitgevoerd conform de richtlijnen.

Alias wijzigen

Wanneer bij het importen van een SSL-certificaat een foutieve waarde voor de alias is opgegeven, zal de Tomcat®-service niet juist starten. In bovengenoemd logbestand zal dan de melding "Alias name does not identify a key entry" verschijnen. Als één van onderstaande wijzigingen wordt toegepast, dan dient de Tomcat®-service opnieuw gestart te worden.

• Keystore Explorer. De aliasnaam kan het eenvoudigst met de tool Keystore Explorer worden aangepast. Hiermee kan het bestand \apps\mkg_pas\conf\mkgapi_uwbedrijfsnaam.nl.jks worden geopend (het wachtwoord van de keystore kluis is nodig!). Het is gebruikelijk dat de aliasnaam een logische waarde heeft, zoals 'mkgapi' of 'wildcard_uwbedrijfsnaam_nl' (vaak wordt in deze naam aangeduid wat voor type certificaat het is en voor welk (sub)domein deze kan worden ingezet).
• Catalina.properties. In het bestand \apps\mkg_pas\conf\catalina.properties is een connector aangemaakt, controleer of de tag 'psc.as.https.keyalias' de juist aliasnaamwaarde bevat.