Transport layer security

When communicating over a computer network with a service that verifies users' identities, it is crucial to use a secure channel. Otherwise, identity credentials such as user name and password, session cookies, or the like can easily be stolen by attackers that listen on the transport layer.

To avoid that, the transport layer security (TLS) protocol was designed to encrypt the traffic between two nodes in a public computer network.

Traffic to and from nevisAuth should always be secured. We recommend using two-way SSL such that the client can trust the nevisAuth instance, but also that nevisAuth can verify and trust the client's identity. In the following chapters, we will examine how to secure incoming and outgoing connections in nevisAuth using keystores and truststores.

Securing server-side communication

To secure connections to nevisAuth, you can configure the connector in the application server configuration:

nevisauth <inst-name> config server

This will open the server.xml of the application Web server instance, which is located in the path /var/opt/nevisauth/default/conf/server.xml, with the following content:

<Connector
 port="8991" address="localhost"
...
 SSLEnabled="true" secure="true" scheme="https" sslProtocol="TLS"
ciphers="TLS_DHE_RSA_WITH_AES_256_CBC_SHA,SSL_DHE_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,
SSL_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,SSL_DHE_RSA_WITH_AES_128_CBC_SHA,
TLS_RSA_WITH_AES_128_CBC_SHA,SSL_RSA_WITH_AES_128_CBC_SHA,SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA,
SSL_RSA_WITH_3DES_EDE_CBC_SHA"
 keystoreFile="/var/opt/keybox/default/node_keystore.jks" keystoreType="JKS"
keystorePass="password"
 clientAuth="true"
 truststoreFile="/var/opt/keybox/default/truststore.jks"
 truststoreType="JKS" truststorePass="password"
 SSLImplementation="org.apache.tomcat.util.net.jsse.JSSEImplementation"
/>

In this configuration, the protocol version and SSL ciphers can be adjusted to your needs. The referenced keystore contains the private key used for the TLS key exchange. For a valid TLS connection, the client must trust the certificate that references this private key. The truststore contains the certificates of all trusted clients. For details on how to manage keys and certificates using nevisKeybox, have a look at the nevisKeybox reference guide.

Securing client-side communication

For outgoing connections, e.g., to establish a connection to an authentication back end, AuthStates can either use AuthState-specific truststores and keystores, or they can use the global truststore and keystore configured as JVM properties.

To configure a global truststore and keystore, use the following command:

nevisauth <inst-name> config vmargs

This will open the configuration at /var/opt/nevisauth/default/conf/vmargs.conf.

-Djavax.net.ssl.keyStore=/var/opt/keybox/default/node_keystore.jks
-Djavax.net.ssl.keyStoreType=JKS
-Djavax.net.ssl.keyStorePassword=password
-Djavax.net.ssl.trustStore=/var/opt/keybox/default/truststore.jks
-Djavax.net.ssl.trustStoreType=JKS
-Djavax.net.ssl.trustStorePassword=password

Many AuthStates can also be configured in a more fine-granular way. This is useful if you want to configure secure connections to a certain back end for a specific AuthState. In this case, you can configure a KeyStore as shown below:

<KeyStore name="MyKeyStore">
 <KeyObject name="MyTrustStore"
 certificate="/var/opt/keybox/nevis/truststore.jks"
/>

Refer to the chapters describing the specific AuthStates to find out how they are using this fine-granular mechanism and how they can be configured to reference the KeyStore element, as this may vary. In most cases, they will initialize the SSL context using the AuthHttpClient described in AuthHttpClient