This article describes how to set up server-side and client-side HTTPS authentication in Tomcat, used in Smart ID Identity Manager. 

For more information, see Default ports in Smart ID. 

Prerequisites

• An SSL server certificate needs to be available in Pkcs#12 format. Make sure that the intended hostname of the Identity Manager Server is included as CN or SAN DNS in the certificate (all expected names/aliases in the HTTPS URL should be included). Typically the customer provides this certificate, issued in the customers PKI environment.

• The certificate revocation list (CRL) in the server certificate needs to be accessible on the Identity Manager clients

For client-side authentication only:

• Client certificates for the end users need to be issued.

• The public part (X.509 certificates) of all issuing CAs that will issue client certificates are required. To build a truststore file for the Tomcat. Only client certificates that match to one of the issuing CAs in that truststore will be able to login later.

Step-by-step instruction

Set up server-side authentication

The most basic HTTPS configuration is the server-side authentication and encrypted connection.

• For docker:
  The Smart ID docker deployment package comes bundled with the optional reverse proxy and load balancer Traefik (see Deploy Smart ID for information about how to configure it). Regardless of which proxy is used, the TLS connection should be configured at this level in the production servers, and not in the Tomcat.

• For WAR file deployment:
  The Tomcat server will get a TLS server certificate to authenticate to the clients and trigger the HTTPS-encrypted connection.
  To set up server-side authentication, do the following steps:

1. Copy the server certificate (.p12 or .pfx file) to the Tomcat Application server.

2. Check which port to use for the HTTPS connection. The default HTTPS port is 443. Tomcat default is 8443, but any other port is allowed as long as there is no collision with any other service on the application server.

3. Edit the server.xml file in <TomcatHome>\conf and add a corresponding HTTPS connector. Adapt the .p12 filename, password and HTTPS port to your environment.

   Example: server.xml connector

   <Connector port="18443" protocol="HTTP/1.1" SSLEnabled="true" maxPostSize="-1" scheme="https" secure="true" sslProtocol="TLS" clientAuth="false" keystoreFile="C:\myCerts\primeCert.p12" keystorePass="123456" keystoreType="PKCS12" />

4. Restart Tomcat.

Set up client-side authentication

If the end users are to authenticate with a client certificate to Identity Manager, an HTTPS connection with client authentication via a two-way SSL handshake, is required. This is typically used for login with smart card or soft token to Identity Manager. 

To set up client-side authentication:

• For docker: not supported

• For WAR file deployment:

1. Create a truststore file. The easiest way to do this is using the java keytool which is part of the JRE and can be found in <java_home>\bin. For each issuing CA, execute the following command:

   Example: create truststore file

   "<java_home>\bin\keytool.exe" -importcert -alias <issuingCA01> -trustcacerts -file issuingCA01.cer -keystore prime.truststore -storepass 123456

   where <java_home> is replaced with the path to java, and <issuingCA01> is replaced with the unique name of each corresponding certificate. Always use the same prime.truststore file.

2. Copy the server certificate .p12 or .pfx file and the truststore file created in the previous step, to the Tomcat application server.

3. Check which port to use for the HTTPS connection. The default HTTPS port is 443. Tomcat default is 8443, but any other port is allowed as long as there is no collision with any other service on the application server.

4. Edit the server.xml file in <TomcatHome>\conf and add a corresponding HTTPS connector. Adapt the .p12 filename, truststore filename, passwords and HTTPS port to your environment.

   Example: server.xml connector

   <Connector port="18444" protocol="HTTP/1.1" SSLEnabled="true" maxPostSize="-1" scheme="https" secure="true" sslProtocol="TLS" clientAuth="true" keystoreFile="C:\cert\primeCert.p12" keystorePass="123456" keystoreType="PKCS12" truststoreFile="C:\cert\prime.truststore" truststorePass="123456" truststoreType="JKS" />

5. Restart Tomcat.

Additional information