Configure Mutual TLS Between Nok Nok Servers

In a Digipass S3 Server deployment it is important to establish trust between the API Server and the Authentication Server. This section explains how to set up TLS authentication between the API Server and the Authentication Server (Auth Server). When you configure this mutual TLS authentication, both the API Server and the Auth Server authenticate each other, and the traffic between the two is encrypted.

Mutual TLS authentication ensures that traffic is secure and trusted in both directions between a client and server. Mutual TLS authentication requires certificates for both the client and server.

You have a choice of using either a Java KeyStore or a pkcs12 KeyStore to store the key and certificate on the client and server. The instructions in this section cover the commands needed for a Java KeyStore.

If you are setting up mutual TLS authentication between the API Server and Auth Server, substitute the API Server for the client and Auth Server for the server in the instructions below.

If you are setting up authentication between your proxy server and the API Server, substitute your proxy server for the client and the API Server for the server.

1. Create the KeyStore on the server.
   
   The following command creates a Java KeyStore, generates a private and public key, and generates a self-signed certificate. Modify the passwords and CN keyword as needed.

keytool -genkeypair -alias serverkey -keyalg RSA -keysize 2048 -dname "CN=<server host name>" -keypass password -storepass password ‑keystore server.jks

2. Create the KeyStore on the client.
   
   The following command creates a Java KeyStore, generates a private key, and generates a self-signed certificate. Modify the passwords and CN keyword as needed.

keytool -genkeypair -alias clientkey -keyalg RSA -keysize 2048 -dname "CN=<client host name>" -keypass password -storepass password ‑keystore client.jks

3. Export the certificate from the client KeyStore and import it into the server KeyStore.
   On the client:

keytool -exportcert -keystore client.jks -storepass password ‑file client-public.cer -alias clientkey

On the server:

keytool -importcert -keystore server.jks -storepass password -file client-public.cer -alias clientcert -noprompt

4. Export the certificate from the server KeyStore and import it into the client KeyStore.

On the server

keytool -exportcert -keystore server.jks -storepass password -file server-public.cer -alias serverkey

On the client

keytool -importcert -keystore client.jks -storepass password -file server-public.cer -alias servercert -noprompt

5. The KeyStores should now be configured as follows:

   • client.jks: Contains the client's TLS private key and server's self-signed certificate.

   • server.jks: Contains the server's TLS private key and client's self-signed certificate.

Verify that the certificates were added correctly using the following commands.

List the client's KeyStore to verify the server's certificate is available:

keytool -list -keystore client.jks -storepass password

List the server's KeyStore to verify the client's certificate is available:

keytool -list -keystore server.jks -storepass password

6. If the API Server is the client, update the API Server's configuration file, nnlgateway.json. Assign the values below to the properties.

   client.jks is used for both client_auth and server_auth configuration because the private key is used for client authentication while the server's certificate is used for server authentication.

   • client_auth.enabled: true

   • client_auth.keystore_file: full path to client.jks

   • client_auth.keystore_passphrase: password for client.jks

   • client_auth.keystore_type: jks

   • server_auth.enabled: true

   • server_auth.truststore_file: Full path to client.jks

   • server_auth.truststore_passphrase: Password for client.jks

   • server_auth.truststore_type: jks

If your proxy server is the client, configuration depends on your implementation. Use client.jks in your proxy to establish the TLS connection to the API Server.

7. Enable mutual TLS authentication in the server's host. Update the Apache Tomcat config file, <TOMCAT_HOME>/conf/server.xml, as in the following example, and restart Tomcat.

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
    maxThreads="150" scheme="https" secure="true"
    clientAuth="true" sslProtocol="TLS" 
    keystoreFile="<path_to>/server.jks" 
    keystoreType="JKS" 
    keystorePass="password"
    truststoreFile="<path_to>/server.jks"
    truststoreType="JKS" truststorePass="password"
/>