How to Change Access Point TLS Certificate (version 2.2.0 and later)?

Owned by Petteri Kivimäki
Last updated: Sept 26, 2023
2 min read

This article applies to new installs of Harmony Access point v2.2.0 and later versions.
For older versions (including upgrades from older versions), see How to Change Access Point TLS Certificate?

By default, the Access Point has a self-signed TLS certificate that's automatically generated during the Access Point installation process. Changing the certificate and/or recreating the private key is not possible through the Access Point UI. Instead, both operations require shell access to the Access Point.

Note about Using Harmony Access Point Container Version

Harmony Access Point configuration is located at /var/opt/harmony-ap/etc instead of /etc/harmony-ap (for convenience, /etc/harmony-ap is a symbolic link to that directory).

Commands can be run inside the container with docker exec (using "sudo" in the container is unnecessary):
docker exec -it <container name> openssl req -x509 -newkey rsa:3072 -keyout harmony-ap-new.key -out harmony-ap-new.crt -days 365 -nodes

Files can be copied to/from a container using docker cp.

Step-by-step guide

The Access Point TLS certificate can be changed by following the steps described below. Instead of OpenSSL, one can also use Java keytool for manipulating the keystore.

  1. First, take backup copy of the TLS keystore file:

    cp -a /etc/harmony-ap/tls-keystore.p12 /etc/harmony-ap/tls-keystore.p12.bak

  2. Generate a new private key and certificate signing request (CSR) by running the command:

    openssl req -x509 -newkey rsa:3072 -keyout harmony-ap-new.key -out harmony-ap-new.crt -days 365 -nodes

If you don't have OpenSSL installed, you can generate the certificate on the Harmony Access Point host.

  1. Enter your CSR details.

  2. Obtain a TLS certificate from a trusted Certificate Authority (CA) using the CSR file.

  3. Once the CA has issued the certificate, rename the certificate file to harmony-ap-new.crt, and copy it to the Access Point.

  4. Check the password of the TLS keystore file from the /etc/harmony-ap/tomcat-conf/server.xml configuration file. The password is located in the "Connector" element's "keystorePass" property.

    1. Take a note of the password (tls_keystore_password).

  5. Create a PKCS#12 container that includes the new key and certificate, and the certificate chain. Use the tls_keystore_password as the export password. Replace the <cert_alias> placeholder with your preferred alias.

    openssl pkcs12 -export -in harmony-ap-new.crt -inkey harmony-ap-new.key -out tls-keystore.p12 -name <cert_alias> -CAfile ca_bundle.crt -caname cacert

  6. Replace the file /etc/harmony-ap/tls-keystore.p12 with the new keystore and update the file permissions.

  7. Restart the harmony-ap service.

    Ubuntu

    Docker

  8. Check that the log file (/var/log/harmony-ap/catalina.out) doesn't contain any TLS related errors.

  9. In case something goes wrong, restore the original files, and restart the harmony-ap service.

Related articles