How to import an SSL certificate?

Renewal/Reissue of Existing Standard SSL Certificate

A renewal or reissue of an existing standard SSL certificate is by far the most common. An SSL certificate has a certain validity, usually 1 year. To continue using the API-based functionalities, like the MKG Shop Floor, the existing SSL certificate must be renewed in a timely manner with a certificate authority. This responsibility lies with the customer. In most cases, the IT party is engaged for this.

For renewing or reissuing an existing SSL certificate, you need the original CSR (certificate signing request) file that contains the same information as used in the initial request. The existing keystore vault is maintained with this.

In most cases, the initial CSR file is located in the folder \apps\mkg_pas1283\conf on the MKG server. Pay close attention to the date/timestamp of the file. If you no longer have the initial CSR file, it is possible to regenerate it.

Step-by-Step Plan

1. Start an MKG client and log in as an administrator or as a user with admin rights.
2. In the System Analysis module, choose the action Regenerate Initial CSR File. Enter the details applicable to your organization and click OK.
3. The generated CSR output is displayed in a pop-up. The created CSR file is also saved to the folder \apps\mkg_pas1283\conf on the MKG server.
4. Use the CSR to renew the existing SSL certificate with your certificate authority.

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

Importing a Standard SSL Certificate

Step-by-Step Plan

1. Start an MKG client and log in as an administrator or as a user with admin rights.
2. In the System Analysis module, choose 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 confirming that the SSL certificate has been successfully imported.
4. Restart the 'MKG Application Server' service.

5. Verify if the SSL certificate has been successfully renewed. This can be done in several ways:

• In an MKG client, go to Help » MKG API… » Management » SSL Expiry Date.
• Open any browser. Go to and check via 'https://[domain]:[port]/mkgbridge' the expiry date of the certificate.

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

Troubleshooting

If the SSL expiry date has not been updated, check if the keystore vault on the server has been updated with today's date/timestamp. The .jks file can be found in the folder \apps\mkg_pas1283\conf on the MKG server. If it has not been updated, two things may be wrong:

1. 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. Double-check if you used the correct CSR file for renewal. Repeat the steps from step 3.
2. An incorrect keystore password was used during import. Verify if the entered password matches the password in the file \apps\mkg_pas1283\conf catalina.properties 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 be necessary to restart the MKG server as well in some cases.

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 places, such as on a domain controller. The keystore vault is also often located elsewhere (centrally) within the server park.

To import a wildcard SSL certificate, you need 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 admin rights.
2. In the System Analysis module, choose 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 confirming that the SSL certificate has been successfully imported.
4. Restart the 'MKG Application Server' service.

5. Verify if the SSL certificate has been successfully renewed. This can be done in several ways:

• In an MKG client, go to Help » MKG API… » Management » SSL Expiry Date.
• Open any browser. Go to and check via 'https://[domain]:[port]/mkgbridge' the expiry date of the certificate.

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

Troubleshooting

If the SSL expiry date has not been updated, check if the keystore vault on the server has been updated with today's date/timestamp. The .jks file can be found in the folder \apps\mkg_pas\conf 1283 on the MKG server. If it has not been updated, two things may be wrong:

1. 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. Double-check if you used the correct CSR file for renewal. Repeat the steps from step 3.
2. An incorrect keystore password was used during import. Verify if the entered password matches the password in the file \apps\mkg_pas1283\conf catalina.properties 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 be necessary to restart the MKG server as well in some cases.

Requesting a New Standard SSL Certificate

Requesting a new standard SSL certificate only applies to a new installation of MKG, where no SSL certificate has been used before. Normally, this falls under the startup/installation tasks performed by a technical consultant from MKG in consultation with the client.

Step-by-Step Plan

1. Start an MKG client and log in as an administrator or as a user with admin rights.
2. In the System Analysis module, choose the action Generate New CSR File (for requesting an initial SSL certificate). Then enter the details 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. Use only alphanumeric characters (letters + numbers). The password will be needed again when installing the requested certificate; 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; keep it safe as well!
3. Then click OK.
4. The generated CSR output is displayed in a pop-up. The created CSR file is also saved to the folder \apps\mkg_pas1283\conf 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. The next step is to import these.

Additional Network/System Settings

The MKG API is designed to connect external applications or services, such as the MKG App or the MKG API-Toolbox, to the MKG environment. With the previous steps, you have made preparations to secure the data traffic using an SSL certificate. To unlock the functionality outside the MKG application server or the internal company network, the following steps need to 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 there are other services unexpectedly active that also use this port, this can be changed in the file \apps\mkg_pas1283\conf\catalina.properties 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 associated or allowed for the Tomcat® instance (file \apps\dlc1283\servers\pasoe\bin\tomcat10.exe).

Firewall Rule WAN » LAN

The firewall that separates the internet connection from the internal network must also have an opening as well as a 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 with the MKG API, a DNS record is needed. This converts a name, such as 'mkgapi.yourcompanyname.nl', into an internet address (the WAN IP address of the company network), such as '8.8.8.8'. When applying SSL certificates, it is standard to apply a name. Adding or adjusting such records must be done with the party where the domain name is hosted.

Troubleshooting

When the previous steps have been successfully completed, the technical setup for the MKG App or the MKG API-Toolbox is ready. If, unfortunately, no connection can be made, first consult the troubleshooting solutions below.

If the SSL expiry date has not been updated, check if the keystore vault on the server has been updated with today's date/timestamp. The .jks file can be found in the folder \apps\mkg_pas1283\conf on the MKG server. If it has not been updated, two things may be wrong:

• 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. Double-check if you used the correct CSR file for renewal.
• An incorrect keystore password was used during import. Verify if the entered password matches the password in the file \apps\mkg_pas1283\conf catalina.properties 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 be necessary to restart the MKG server as well in some cases.

Check Reachability 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'. When a page is displayed with the text "REST adapter", it means the service is active within the company's internal 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'. When a page is displayed with the text "REST adapter", it means the service is active outside the company's internal network and the technical setup has been carried out correctly. If this is not the case, the setup was not executed according to the guidelines.

Change Alias

When an incorrect value for the alias is entered during the import of an SSL certificate, the Tomcat® service will not start correctly. The above-mentioned log file will then display the message "Alias name does not identify a key entry". If one of the following changes is applied, the Tomcat® service must be restarted.

• Keystore Explorer. The alias name can be most easily adjusted with the Keystore Explorer tool. This allows the file \apps\mkg_pas1283\conf\mkgapi_yourcompanyname.nl.jks to be opened (the password for 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 file \apps\mkg_pas1283\conf\catalina.properties, a connector is created, check if the tag 'psc.as.https.keyalias' contains the correct alias name value.