How to import an SSL certificate in MKG

Renewing a standard SSL certificate

A commercial SSL certificate has a validity of approximately 1 year. To continue using, among others, the Shop Floor, it must be renewed in time with an SSL provider/certificate authority. This responsibility lies with the customer. In most cases, the IT party is engaged by the customer for this.

For renewing or reissuing an existing SSL certificate, you will need the original CSR (Certificate Signing Request) file again, depending on your SSL provider. The CSR file (mkgapi.<domain name>.csr) can be found in the \apps\mkg_pas\conf directory on the MKG server. If you can no longer find it there, it is possible to regenerate it using the steps below.  

1. Start an MKG client and log in as an administrator or as a user with administrator rights.
2. In the System Analysis module, select the action Regenerate initial CSR file. Enter the information applicable to your organization and click OK. (If this module is not in your menu, you can call it up by searching for system analysis in the search field at the top right.)
3. The generated CSR output will be displayed in a pop-up. The created CSR file is also written to the \apps\mkg_pas\conf directory on the MKG server.

Importing a standard SSL certificate

Importing can be done in various ways described below. Choose the method that best suits your situation:

1. Java keytool: command line, no MKG account required, requires a certificate bundle (root, intermediate, end-user).
2. MKG client: via the MKG GUI, MKG account required, requires a certificate bundle (root, intermediate, end-user).
3. KeyStore Explorer: open source tool with GUI, no MKG account required. This method offers the most options, for example, it can handle .PFX and .P12 files and you can also generate new Java KeyStore(s) with it. 

Java Keytool Method

1. Create a new .txt file and sequentially paste the root, intermediate, and end-user certificate obtained from the certificate bundle file. The .txt file must consist of 3 blocks:

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

2. Rename the *.txt file to new_certificate.crt. This now contains the entire certificate chain.
3. Make a backup of the existing keystore (*.jks file) in \\apps\mkg_pas\conf.
4. Open an elevated Command prompt and navigate to \\apps\dlc1176\jdk\bin\
5. Execute the following command:

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

6. You will be prompted for the keystore password. 
   • Keystore password can be found in the file \\apps\mkg_pas\conf\catalina.properties under psc.as.https.keypass
   • Alias can also be found in the catalina.properties file under psc.as.https.keyalias
7. If the certificate could be imported correctly, the following message will appear: Certificate reply was installed in keystore
8. Restart the 'MKG Application server' service to effectuate the updated keystore.

KeyStore Explorer Method

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

Pre-information: MKG works with a Java KeyStore (vault). To generate a (new) Java KeyStore, the following is required:

• Private key and end-user certificate
• Root and intermediate certificate

If you do not have a private key, you can export it from an existing Java KeyStore or a PFX bundle. This is done as follows:

1. Open Keystore Explorer.
2. Open the existing JKS (Java keystore vault) or P12 or PFX.

Note: Passcode can be found in the catalina.properties file in the case of a JKS. (\apps\mkg_pas\conf)

3. Click on the certificate > right-click > Export > Export Private Key. You will be asked for the keystore password again.
4. Choose OpenSSL as the type.
5. Uncheck Encrypt and click Export.

Export client, intermediate, and root certificate:

6. Click on the certificate > right-click > View Details > Certificate Chain Details
7. Export the certificate for each of the 3 lines (root, intermediate, and client) by clicking on them and clicking Export.

Generate a new Java KeyStore:

1. Choose New > JKS
2. Right-click > Import Key Pair
3. Choose OpenSSL
4. Uncheck Encrypted Private Key.
5. Select the OpenSSL Private Key file and for Certificate File the Client certificate and click Import.
6. Enter 'mkgapi' for Enter Alias.

Note: mkgapi is the default alias. This can sometimes differ. If the entered alias differs from the one filled in the catalina.properties file, Tomcat will give an error when starting.

7. Enter New Password and the password found in the catalina.properties file. The line starts with: psc.as.https.keypass.
8. Click on the certificate > right-click > Edit Certificate Chain > Append Certificate. Choose the intermediate certificate.

Note: If a mismatch occurs, the wrong certificate has been chosen. Choose the other file.

9. Repeat step 13 and now choose the root certificate.
10. Choose File > Save KeyStore As and save it as *.JKS.
11. Temporarily create a copy of the current mkgapi_<domain name>.JKS file in the \\apps\mkg_pas\conf folder.
12. Replace the current JKS file with the new JKS file.
13. Restart the MKG Application service (=web server).
14.  

Method via MKG client

1. Start an MKG client and log in as an administrator or as a user with administrator rights.
2. In the System Analysis module, select the action Import standard SSL certificate.
3. Select the 'root, intermediate, and end-user' certificate (*.cer or *.crt) and fill in the rest of the details including the keystore password and click OK. A message will appear that the SSL certificate has been successfully imported.
4. Restart the 'MKG Application server' service to effectuate the updated keystore.

5. Check if the SSL certificate has been successfully renewed. This can be done in various ways:
   • Go to Help in an MKG client
     » MKG API… » 'Management' tab » SSL expiration date.
   • Open any browser. Go to and check the certificate's expiration date via 'https://[domain]:[port]/mkgbridge'.

Are the domain and/or port number unknown? The domain can be found in the \apps\mkg_pas\conf\server.xml file on the MKG server (see tag 'Keystorefile'). The port number can be found in the \apps\mkg_pas\conf\catalina.properties file (see tag 'psc.as.https.port').

Troubleshooting

If the SSL expiration date has not been updated, check whether the keystore vault on the server has been updated with today's date/timestamp. The .jks file can be found in the \apps\mkg_pas\conf directory on the MKG server. If this has not been updated, two things may be happening:

• An incorrect CSR was used for renewing/reissuing the SSL certificate. As a result, the private key of the keystore vault does not match the renewed SSL certificate. Check again if you used the correct CSR file when renewing. Repeat the steps from step 3.
• An incorrect keystore password was used during import. Check if the entered password matches the password in the \apps\mkg_pas\conf catalina.properties file on the MKG server (see tag 'psc.as.https.keypass'). Try importing the SSL certificate again.

If the .jks file has been updated and you have already restarted the MKG Application server, it may sometimes be necessary to also restart the MKG server.

Importing a *wildcard SSL certificate

Wildcard SSL certificates can be used for multiple domain names. CSR files needed for requesting wildcard SSL certificates are often generated in other locations, such as on a domain controller. The keystore vault is also often located in another (central) place within the server park.

To import a wildcard SSL certificate, you will need, among other things, the 'root, intermediate, and end-user' (client) certificate including the private key.

Step-by-step plan

1. Start an MKG client and log in as an administrator or as a user with administrator rights.
2. In the System Analysis module, select the action Import wildcard SSL certificate.
3. Select the root, intermediate, and end-user certificate (*.cer or *.crt), the private key file, and fill in the rest of the details including the keystore password and click OK. A message will appear that the SSL certificate has been successfully imported.
4. Restart the 'MKG Application server' service.

5. Check if the SSL certificate has been successfully renewed. This can be done in various ways:
   • Go to Help in an MKG client
     » MKG API… » 'Management' tab » SSL expiration date.
   • Open any browser. Go to and check the certificate's expiration date via 'https://[domain]:[port]/mkgbridge'.

Are the domain and/or port number unknown? The domain can be found in the \apps\mkg_pas\conf\server.xml file on the MKG server (see tag 'Keystorefile'). The port number can be found in the \apps\mkg_pas\conf\catalina.properties file (see tag 'psc.as.https.port').

Troubleshooting

If the SSL expiration date has not been updated, check whether the keystore vault on the server has been updated with today's date/timestamp. The .jks file can be found in the \apps\mkg_pas\conf directory on the MKG server. If this has not been updated, two things may be happening:

• An incorrect CSR was used for renewing/reissuing the SSL certificate. As a result, the private key of the keystore vault does not match that of the renewed SSL certificate. Check again if you used the correct CSR file when renewing. Repeat the steps from step 3.
• An incorrect keystore password was used during import. Check if the entered password matches the password in the \apps\mkg_pas\conf catalina.properties file on the MKG server (see tag 'psc.as.https.keypass'). Try importing the SSL certificate again.

If the .jks file has been updated and you have already restarted the MKG Application server, it may sometimes be necessary to also restart the MKG server.

Requesting a new standard SSL certificate

Requesting a new standard SSL certificate is only applicable for a new installation of MKG, where an SSL certificate has not been used before. Normally, these tasks fall under the startup/installation work carried out by an MKG technical consultant in consultation with the customer.

Step-by-step plan

1. Start an MKG client and log in as an administrator or as a user with administrator rights.
2. In the System Analysis module, select the action Generate new CSR file (for requesting initial SSL certificate). Then enter the information applicable to your organization:
   • Common Name. mkgapi.yourcompanyname.nl. The domain name yourcompanyname.nl must be in your possession. Additionally, it is necessary to be able to adjust DNS records for this domain.
   • Company Name. Company Name B.V. Enter the full company name as known to the authorities. Depending on the type of certificate purchased, this must match exactly.
   • Department. IT.
   • City. Enter the city of establishment as known to the authorities. Depending on the type of certificate purchased, this must match.
   • Province. Enter the province in which the above city is located.
   • Country. Enter the two-letter country code according to the ISO 3166-1 standard.
   • Keystore Password. Enter a strong password of at least 6 characters here. Use only alphanumeric characters (letters + numbers). The password will be needed again when installing the requested certificate; so keep it safe!
   • Alias. It is common to fill in the first part of the 'Common Name' here. The alias will be needed again when installing the requested certificate; so keep this safe as well!
3. Then click OK.
4. The generated CSR output will be displayed in a pop-up. The created CSR file is also written to the \apps\mkg_pas\conf directory on the MKG server. Finally, an SSL keystore vault is created, in which the new certificate can be imported.
5. Use the CSR to request a new SSL certificate from your certificate authority.

When you have successfully requested the SSL certificate, you will receive a certificate bundle from your certificate authority. This includes the 'root, intermediate, and end-user' (client) certificate, among other things. The next step is to import these.

Additional network/system settings

The MKG API is intended to connect external applications or services, such as the MKG App or the MKG API Toolbox, with the MKG environment. With the previous steps, you have made preparations to secure data traffic using an SSL certificate. To unlock the functionality outside the MKG application server or the internal company network, the following steps must be applied.

Apply firewall rules

The MKG API uses an Apache Tomcat® instance, where the connector is set to listen on port 443 TCP. If other services are unexpectedly active that also use this port, this can be changed in the \apps\mkg_pas\conf\catalina.properties file on the MKG server (see tag 'psc.as.https.port').

Firewall rule on application server

The firewall active on the MKG application server must be opened for traffic on port 443 TCP. If desired, the traffic can only be linked or allowed for the Tomcat® instance (file \apps\dlc1176\servers\pasoe\bin\tomcat8.exe).

Firewall rule WAN > LAN

The firewall that separates the internet connection from the internal network must also have an opening and forwarding to the MKG server. An example rule:

• Destination host: IP address of the MKG server
• Source host: ALL
• Inbound port: 443 (as long as the port in the Tomcat® instance has not been changed)
• Outbound port: 443 (if this is already in use, then 7443, 8443, or 9443 is an alternative)
• Data mode: TCP

Apply a DNS record

To connect to the MKG API, a DNS record is needed. Here, a name, such as 'mkgapi.yourcompanyname.nl', is converted to an internet address (the WAN IP address of the company network), such as '8.8.8.8'. When applying SSL certificates, it is actually standard to apply a name. Adding or adjusting such records must be done with the party where the domain name is hosted.

Troubleshooting

If the SSL expiration date has not been updated, check whether the keystore vault on the server has been updated with today's date/timestamp. The .jks file can be found in the \apps\mkg_pas\conf directory on the MKG server. If this has not been updated, two things may be happening:

• An incorrect CSR was used for renewing/reissuing the SSL certificate. As a result, the private key of the keystore vault does not match that of the renewed SSL certificate. Check again if you used the correct CSR file when renewing.
• An incorrect keystore password was used during import. Check if the entered password matches the password in the \apps\mkg_pas\conf catalina.properties file on the MKG server (see tag 'psc.as.https.keypass'). Try importing the SSL certificate again.

If the .jks file has been updated and you have already restarted the MKG Application server, it may sometimes be necessary to also restart the MKG server.

Check accessibility in browser

• Internal test. Start a browser session (e.g., in Google Chrome or Mozilla Firefox) on the application server to 'https://localhost/mkg' (or to 'https://localhost/mkg:7443'. If a page is displayed with the text "REST adapter", it means that the service is active within the own company network.
• External test. Start a browser session (e.g., in Google Chrome or Mozilla Firefox) on a workstation to 'https://mkgapi.yourcompanyname.nl/mkg' (or to 'https://mkgapi.yourcompanyname.nl:7443/mkg'. If a page is displayed with the text "REST adapter", it means that the service is active outside the own company network and that the technical setup has been executed correctly. If this is not the case, the setup has not been executed according to the guidelines.

Change alias

If an incorrect value for the alias was provided when importing an SSL certificate, the Tomcat® service will not start correctly. The message "Alias name does not identify a key entry" will then appear in the aforementioned log file. If one of the changes below is applied, the Tomcat® service must be restarted.

• Keystore Explorer. The alias name can be easily adjusted with the Keystore Explorer tool. This allows the \apps\mkg_pas\conf\mkgapi_yourcompanyname.nl.jks file to be opened (the password of the keystore vault is needed!). It is common for the alias name to have a logical value, such as 'mkgapi' or 'wildcard_yourcompanyname_nl' (often this name indicates what type of certificate it is and for which (sub)domain it can be used).
• Catalina.properties. In the \apps\mkg_pas\conf\catalina.properties file, a connector has been created, check if the tag 'psc.as.https.keyalias' contains the correct alias name value.