How to Import an SSL Certificate

Renew/reissue 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. In order to continue using the API-based functionalities, such as the MKG Shop Floor, the existing SSL certificate must be renewed in time with a certificate authority. This responsibility lies with the customer. In most cases, the IT partner is called in for this.

To renew or reissue an existing SSL certificate, you need the original CSR (certificate signing request) file that contains the same information as the initial request was made. This maintains the existing keystore vault.

In most cases, the initial CSR file is located in the \apps\mkg_pas1283\conf folder on the MKG server. Look carefully at the date/timestamp of the file. If you no longer have the initial CSR file available, it is possible to generate it again.

Step-by-step

1. Start an MKG client and log in as an administrator or as a user with administrative rights.
2. Choose in the System Analysis module for the Regenerate Initial CSR File action. Enter the details that apply to your organization and click OK.
3. The generated CSR output is shown in a pop-up. The created CSR file is also written to the \apps\mkg_pas\conf folder on the MKG server.
4. Use the CSR to renew the existing SSL certificate with your certificate authority.

If you were able to successfully renew 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 it.

Import a standard SSL certificate

Step-by-step

1. Start an MKG client and log in as an administrator or as a user with administrative rights.
2. Choose in the System Analysis module for the Import Standard SSL Certificate action.
3. Select the 'root, intermediate and end-user' certificate (*.cer or *.crt) and fill in the rest of the information including the keystore password and click OK. A message appears that the SSL certificate has been successfully imported.
4. Restart the 'MKG Application Server' service.

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

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

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 expiration date has not been updated, check that the keystore vault on the server has been updated with today's date/timestamp. The .jks file can be found in the \apps\mkg_pas1283\conf folder on the MKG server. If it is not updated, there could be two things going on:

1. A different CSR was used for the renewal/reissue of the SSL certificate. As a result, the private key of the keystore vault does not match the renewed SSL certificate. Double check that you used the correct CSR file when renewing. Do the steps from step 3 again.
2. An incorrect keystore password was used during the import. Check whether 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 in some cases to also restart the MKG server.

Import a wildcard SSL certificate

Wildcard SSL certificates can be used for multiple domain names. CSR files required to request wildcard SSL certificates are often generated elsewhere, such as on a domain controller. The keystore safe is often also located at another (central) location within the server park.

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

Step-by-step

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

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

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

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 expiration date has not been updated, check that the keystore vault on the server has been updated with today's date/timestamp. The .jks file can be found in the \apps\mkg_pas1283\conf folder on the MKG server. If it is not updated, there could be two things going on:

1. A different CSR was used for the renewal/reissue of the SSL certificate. As a result, the private key of the keystore vault does not match that of the renewed SSL certificate. Check again whether you used the correct CSR file when renewing. Do the steps from step 3 again.
2. An incorrect keystore password was used during the import. Check whether 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 in some cases to also restart the MKG server.

Request a new standard SSL certificate

Requesting a new standard SSL certificate only applies to a new installation of MKG, where an SSL certificate has not been used before. Normally, the start-up/installation activities are carried out by a MKG technical consultant in consultation with the customer.

Step-by-step

1. Start an MKG client and log in as an administrator or as a user with administrative rights.
2. Choose in the module System Analysis for the Generate New CSR File action (for initial SSL certificate requests). Then enter the details that apply to your organization:
   • General Name. mkgapi.yourcompany.nl. You must own the domain name yourcompany.nl. In addition, 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 it is known to the authorities. Depending on the type of certificate purchased, it must match exactly.
   • Department. IT.
   • Location. Enter the place of business, as it is 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. Only use alphanumeric characters (letters + numbers). The password will be required again when installing the requested certificate; so keep this well!
   • Alias. It is customary 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 well!
3. Then click OK.
4. The generated CSR output is shown in a pop-up. The created CSR file is also written to the folder \apps\mkg_pas1283\conf on the MKG server. Finally, an SSL keystore vault is created, into 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 applied for 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 it.

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, to the MKG environment. With the previous steps you have made the preparations to secure data traffic using an SSL certificate. To unlock the functionality outside the MKG application server or the internal company network, it is necessary to apply the following steps.

Apply firewall rules

The MKG API uses an Apache Tomcat® instance, with the connector set to listen on port 443 TCP. In the unlikely event that other services are 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 that is active on the MKG application server must be opened for traffic on port 443 TCP. Optionally, the traffic can be bound or allowed only for the Tomcat® instance (\apps\dlc1283\servers\pasoe\bin\tomcat10.exe file).

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 modified)
• Outbound port: 443 (if already in use then 7443, 8443 or 9443 is an alternative)
• Data mode: TCP

Apply a DNS record

A DNS record is required to connect to the MKG API. 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 modifying such records must be done at the party where the domain name is registered.

Troubleshooting

When the previous steps have been successfully completed, the technical setup for the MKG App or the MKG API Toolbox is ready. In the unlikely event that a connection cannot be made, first consult the troubleshooting below.

If the SSL expiration date has not been updated, check that the keystore vault on the server has been updated with today's date/timestamp. The .jks file can be found in the \apps\mkg_pas1283\conf folder on the MKG server. If it hasn't been updated, there could be two things going on:

• A different CSR was used for the renewal/reissue of the SSL certificate. As a result, the private key of the keystore vault does not match that of the renewed SSL certificate. Check again whether you used the correct CSR file when renewing.
• An incorrect keystore password was used during the import. Check whether 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 in some cases to also restart the MKG server.

Check accessibility in browser

• Internal test. On the application server, start a browser session (e.g. in Google Chrome or Mozilla Firefox) to "https://localhost/mkg" (or to "https://localhost/mkg:7443". When a page is displayed that says "REST adapter", it means that the service is active within its own corporate network.
• External test. At a client, start a browser session (for example in Google Chrome or Mozilla Firefox) to 'https://mkgapi.yourcompanyname.nl/mkg' (or to 'https://mkgapi.yourcompanyname.nl:7443/mkg'. When a page is displayed with the text "REST adapter", this means that the service is active outside the company's own network and that the technical configuration has been carried out correctly, if this is not the case, the configuration has not been carried out in accordance with the guidelines.

Change alias

If an incorrect alias value is specified 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 above log file. If one of the changes below is applied, the Tomcat® service must be restarted.

• Keystore Explorer. The alias name can most easily be modified using the Keystore Explorer tool. With this the file \apps\mkg_pas1283\conf\mkgapi_yourcompanyname.nl.jks can be opened (the password of the keystore vault is required!). It is usual for the alias name to have a logical value, such as 'mkgapi' or 'wildcard_yourcompanyname_nl' (this name often indicates what type of certificate it is and for which (sub)domain it can be used).
• Catalina.properties. A connector has been created in the \apps\mkg_pas1283\conf\catalina.properties file, check whether the 'psc.as.https.keyalias' tag contains the correct alias name value.