How to import an SSL certificate in MKG?

1. Preparation: Obtain CSR file

To request or renew an SSL certificate, you need a CSR file. For renewal with the SSL provider, the same (original) CSR file must be used each time. 

You can find the CSR in \\apps\mkg_pas12XX\conf\mkgapi.<domain>.csr on the MKG server. If it is no longer present, follow the steps below to regenerate the CSR:

1. Start an MKG client and log in with an account with administrator rights.
2. Go to System Analysis > Regenerate initial CSR file.
3. Enter the organization details.
4. For Keystore details:
   • Enter keystore password.
     • You can find this in the \\apps\mkg_pas12XX\conf\catalina.properties file on the MKG server. (see line psc.as.https.keypass).
   • Enter alias.
     • You can find this in the \\apps\mkg_pas12XX\conf\catalina.properties file on the MKG server. (see line psc.as.https.keyalias).
5. CSR appears in a pop-up and is saved in the specified folder.

2. Preparation: Request SSL certificate 

Request the SSL certificate from your SSL provider using the CSR. With some SSL providers, it is not necessary to resubmit the CSR. You will then receive a certificate bundle consisting of, among others, a:

• End-user certificate (the domain)
• Intermediate certificate
• Root certificate

3.1 (Standard) SSL certificate import

Method 1 - Via the MKG client (most user-friendly)

Required: MKG client, MKG account with administrator rights, new certificate bundle. 

Steps:

1. Start MKG and log in with an account with administrator rights.
2. Go to System Analysis > Import standard SSL certificate.
3. Select root, intermediate, and end-user certificates (*.crt / *.cer).
   • The root and intermediate certificate is often found in the subfolder 'Root certificates' within the certificate bundle.
   • The root certificate is in most cases recognizable by the naming 'root'.
   • The end-user (customer) certificate is located at the top level of the certificate bundle and will include the domain name in its naming.

4. Enter the Common Name (CN). Example: mkgapi.metaalbedrijf-jansen.nl
5. Enter keystore password. 
   • You can find this in the \\apps\mkg_pas12XX\conf\catalina.properties file on the MKG server. (see line psc.as.https.keypass).

6. Enter alias. Default is 'mkgapi'. 
   • You can find this in the \\apps\mkg_pas12XX\conf\catalina.properties file on the MKG server. (see line psc.as.https.keyalias).

7. Restart the MKG Application 12XX server Service to activate the certificate.

Note: Users experience a brief interruption in MKG. Logging out in advance is not necessary.

Method 2 - KeyStore Explorer (Open source GUI tool from third parties)

Required: KeyStore Explorer (open source), new certificate bundle and private key.
Download link: https://keystore-explorer.org/downloads.html  (including JRE)

Steps:

1. Open the existing JKS or PFX in KeyStore Explorer. (optional)
2. Export the private key and the individual certificates. (optional)
3. Generate a new JKS. (File > New JKS)
4. Click on Tools > Import Key Pair > OpenSSL > Select Private Key + End-user certificate. 
5. You will be asked for the alias. Default is 'mkgapi'.
   • You can find this in the \\apps\mkg_pas12XX\conf\catalina.properties file on the MKG server. (see line psc.as.https.keyalias).
6. Add the intermediate and root via Edit Certificate Chain > Append Certificate

7. Save the file as .jks. You will be asked for a password. Use the existing keystore password.
   • You can find this in the \\apps\mkg_pas12XX\conf\catalina.properties file on the MKG server. (see line psc.as.https.keyalias)

3.2 Importing Wildcard SSL certificate

Same principle, but in Method 1 - Via the MKG client:

• Choose in System Analysis > Import wildcard SSL certificate.
• You also need the private key in addition to the certificate bundle.
• Pay attention to correct alias & Keystore password.

4. Validation 

Check SSL certificate expiry date:

• In MKG client: Help > MKG API > Management tab > SSL expiry date.
• In browser, request certificate details: https://<domain>:<port>/mkgbridge.

Troubleshooting

Common issues:

• Incorrect CSR used → private key mismatch. Use the correct CSR.
• Wrong keystore password →  Keystore was tampered with, or password was incorrect. Use the keystore password from the catalina.properties file.
• Incorrect order of Root and Intermediate certificate specified. Check the order.

Additional network/system settings

To expose MKG functionalities like the API externally, the following steps need to be applied.

1. Firewall MKG server: Open port 443 (default) TCP on the MKG server.
   • There may be a different SSL port. You can find this in the \\apps\mkg_pas12XX\conf\catalina.properties file on the MKG server. (see line psc.as.https.port).
2. Firewall rule: set forwarding (TCP) from WAN → LAN (SSL port).

3. Create DNS record such as mkgapi.yourcompany.nl → WAN-IP.