Configure TLS for the API Server

Communication between the Nok Nok App SDK in your apps running on end user devices and the Nok Nok API Server must be secured using TLS. This section lists the steps necessary to enable TLS in Apache Tomcat where the Nok Nok API Server is deployed.

You may skip this section if the TLS connection from your apps terminates at a load balancer or a firewall in front of the Nok Nok API Server.

Step 1: Obtain a valid server certificate and private key for your server.

You will need a server certificate (server.crt) and the private key (server.pem) for your server. The certificate must be issued by a Certificate Authority (CA) so that your end user devices can verify the authenticity of your server.

Step 2: Enable TLS in Apache Tomcat

Once you have a valid server certificate (server.crt) and private key (server.pem), update the Apache Tomcat configuration file(s) to use the server certificate and private key. To enable TLS encryption in a standard Apache Tomcat setup, follow the steps below.

1. Edit $TOMCAT_HOME/conf/server.xml in a text editor.

2. Use openssl to export the server.crt file as a pkcs12, pkcs11, or jks certificate. You are prompted to enter and confirm the export password. This password is set in the keystorePass in the server.xml file.

openssl pkcs12 -export -in <path to your server.crt file> -out <certificate name.pkcs12> -name "<certificate name>" -inkey <path to your server.key file>

3. Test to see if the file contains the key:

keytool -list -v -keystore server.pkcs12 -storetype pkcs12

4. Edit $TOMCAT_HOME/conf/server.xml. Modify the <Connector> element for a TLS connector that is included in the default server.xml. Edit it to use your server certificate (server.crt) and private key (server.pem) files.

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150" SSLEnabled="true">
<SSLHostConfig>
<Certificate certificateKeystoreFile="<path to your server.pkcs12 file>"
certificateKeystoreType="PKCS12"
certificateKeystorePassword="*******"
type="RSA" clientAuth="false" sslProtocols="TLSv1.2"/>
</SSLHostConfig>
</Connector>

Also ensure that the <Connector> element defines only modern cipher suites:

ciphers="TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_DSS_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_SHA256,TLS_ECDHE_RSA_WITH_AES_128_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_SHA,TLS_ECDHE_RSA_WITH_AE_256_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_SHA384,TLS_ECDHE_RSA_WITH_AES_256_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_SHA,TLS_DHE_RSA_WITH_AES_128_SHA256,TLS_DHE_RSA_WITH_AES_128_SHA,TLS_DHE_DSS_WITH_AES_128_SHA256,TLS_DHE_RSA_WITH_AES_256_SHA256,TLS_DHE_DSS_WITH_AES_256_SHA,TLS_DHE_RSA_WITH_AES_256_SHA"

5. Save the file and exit.

6. Restart Apache Tomcat by opening a terminal and issuing these commands:

<TOMCAT_HOME>/bin/shutdown.sh
<TOMCAT_HOME>/bin/startup.sh

Apache Tomcat should now be configured to serve connections using TLS. Before proceeding, confirm that the configuration is correct. For more information, see Tomcat documentation.

Step 3: Confirm that the TLS Configuration is Correct

1. Obtain the IP address of the server using the ip addr command or the domain name.

2. Check that the Apache web server is correctly configured to use TLS by running:

openssl s_client -connect <your_ip_address or domain name>:<port>

If your server is configured correctly, the output of this command displays the details of the certificate you configured in Apache Tomcat, and information on the TLS connection established by this command. You now have a functioning installation of Apache Tomcat configured to use TLS encryption to protect HTTP communications.