Hoe importeer je een SSL-certificaat in MKG?

Verlenging/heruitgifte bestaand standaard SSL-certificaat

Een verlenging of heruitgifte van een bestaand standaard SSL-certificaat komt verreweg het vaakst voor. Een SSL-certificaat heeft een bepaalde geldigheid, meestal 1 jaar. Om gebruik te kunnen blijven maken met de op API gebaseerde functionaliteiten, zoals de MKG Shop Floor, moet het bestaande SSL-certificaat tijdig worden verlengd bij een certificaatautoriteit. Deze verantwoordelijkheid ligt bij de klant. In de meeste gevallen wordt hiervoor de IT-partij ingeschakeld.

Voor het verlengen óf voor een heruitgifte van een bestaand SSL-certificaat heb je het oorspronkelijke CSR (Certificate Signing Request)-bestand nodig dat dezelfde informatie bevat als waarmee de initiële aanvraag is verricht. De bestaande keystore-kluis wordt hiermee in stand gehouden.

In de meeste gevallen bevindt het initiële CSR-bestand zich in de map \apps\mkg_pas\conf op de MKG server. Kijk goed naar de date/timestamp van het bestand. Mocht je het initiële CSR-bestand niet meer voorhanden hebben, dan is het mogelijk om deze opnieuw te genereren.

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 initieel CSR bestand opnieuw. Geef de gegevens in die van toepassing zijn op jouw organisatie en klik op OK.
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.
4. Gebruik de CSR om het bestaande SSL-certificaat te verlengen bij je certificaatautoriteit.

Als je het SSL-certificaat met succes hebt kunnen verlengen, 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.

Een standaard SSL-certificaat importeren

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

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

Wanneer voorgaande stappen succesvol zijn uitgevoerd, is de technische inrichting voor de MKG App of de MKG API-Toolbox gereed. Mocht er onverhoopt toch geen verbinding gemaakt kunnen worden, raadpleeg dan eerst onderstaande probleemoplossingen.

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.