Configure Nginx to Direct HTTPS Requests to Universal Messaging

Universal Messaging 10.11 | Administration Guide | Using Nginx with Universal Messaging | Configure Nginx to Direct HTTPS Requests to Universal Messaging

Use SSL Passthrough

With SSL passthrough, traffic passes through a proxy server to a backend server without being decrypting on the proxy server. Proxy SSL passthrough is the simplest way to configure SSL in a proxy server but is suitable only for smaller deployments.

To use SSL passthrough with Nginx, add the following code to the nginx.conf file. If Nginx is running, you must reload it for the changes to take effect.

server {
listen 443 ssl;
server_name proxy_server;

#Setting Nginx to serve HTTPS traffic requires private keys and certificates.
ssl_certificate /etc/nginx/certificates/servercerts/server.pem;
ssl_certificate_key /etc/nginx/certificates/servercerts/server.key;
ssl_trusted_certificate /etc/nginx/certificates/servercerts/truststore.crt;

location / {
#Important: Nginx must continuously send data to the Universal Messaging client rather than
#buffering it.
proxy_buffering off;

#SSL settings for validating Nginx by the Universal Messaging server
proxy_ssl_certificate /etc/nginx/certificates/servercerts/server.pem;
proxy_ssl_certificate_key /etc/nginx/certificates/servercerts/server.key;
proxy_ssl_trusted_certificate /etc/nginx/certificates/servercerts/truststore.crt;

#Important: Configure proxy http protocol version 1.1 to enable the connection keepalive
#and specify an empty string for the connection header.
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_pass https://umhost:port;
}
}

Use SSL Termination

SSL termination or offloading decrypts all HTTPS traffic on the proxy server. SSL offloading allows data to be inspected as the data passes between the proxy server and the backend server. It also reduces CPU demand on an application server by decrypting data in advance. However, SSL offloading is vulnerable to attacks because the data travels unencrypted between the proxy server and the application server.

Nginx decrypts the request before sending it to the backend server and encrypts the response before sending it to the client. This action takes extra CPU cycles to encrypt and decrypt messages.

Add the following code to the nginx.conf file with the nhps interface that you configured for your Universal Messaging server and reload Nginx:

server {
listen 443 ssl;
server_name proxy_server;

#SSL certificates and keys
ssl_certificate /etc/nginx/certificates/servercerts/server.pem;
ssl_certificate_key /etc/nginx/certificates/servercerts/server.key;
ssl_trusted_certificate /etc/nginx/certificates/servercerts/truststore.crt;

location / {
#Important: Nginx must continuously send data to the UM client rather than buffering it.
proxy_buffering off;

#Important: Configure proxy http protocol version 1.1 to enable the connection keepalive
#and specify an empty string for the Connection header.
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_pass http://umhost:port;
}
}

SSL Directives

The following table describes the Nginx SSL directives to configure and their required values for redirecting HTTPS traffic to Universal Messaging.

Directives	Required Value	Description
ssl_certificate	<certificate_file_path>	Server certificate file in pem format.
ssl_certificate_key	<certificate_key_file_path>	Server private key in pem format.
ssl_trusted_certificate	<truststore_file_path>	File with trusted CA certificates in pem format used to verify clients.
proxy_ssl_certificate	<certificate_file_path>	Specifies a file with the certificate in pem format used for authentication to a proxied HTTPS server.
proxy_ssl_certificate_key	<certificate_file_path>	Specifies a file with the secret key in pem format used for authentication to a proxied HTTPS server. You can specify the value engine:name:id instead of the file (1.7.9), which loads a secret key with the specified ID from the OpenSSL engine name.
proxy_ssl_trusted_certificate	<truststore_file_path>	Specifies a file with trusted CA certificates in pem format used to verify the certificate of the proxied HTTPS server.

Client Code

Update the keystore and truststore certificates of the client in the session attributes in the createSession() method of the following program:

public void createSessionAndCreateChannel(String arg) throws Exception {
nSessionAttributes attr = new nSessionAttributes(“nhps://locahost:443”);
attr.setName("client");
attr.setTruststore("C:\\certs\\truststore.jks", "nirvana");
attr.setKeystore("C:\\certs\\myclient.jks", "nirvana");
attr.setSSLProtocol("TLS");
nSession session = nSessionFactory.create(attr);
session.init();
nChannel chan = session.createChannel(new nChannelAttributes(“MyChannel”));
session.close();

}

The program creates a session to the Universal Messaging sever that is specified in the proxy_pass location directive of the nginx.conf file.

When you run the program specify the Nginx HTTPS URL in the format nhps://nginxhost:port, for example, nhps://locahost:443. You can also create a channel on the Universal Messaging server with the proxied Nginx server.