Tech tip: deploy NGINX in container with client certificate verification

In this post I’m going to show how prepare and deploy certificate and CA for web server NGINX and deploy client certificate to authorize web clients to access in a more safety way, restful API, SOAP or wathever is running on HTTPs. All is realized using docker and docker-compose to bring together all pieces of this chain. This could be useful in mobile development to authorize (or revoke) mobile application accessing to web services and eliminate the problem of unauthorized connection (like bot and robot).

image

The following instructions are intend for a simple deployment; for large deployment an internal CA, an automatic software distribution and docker-swarm or kube are quite mandatory to don’t make sysadmin crazy (…and trust me! this is not a big deal Winking smile )

You could find all files included in this example here: https://github.com/linoproject/blog/tree/master/nginx_certificate

Preparing self certificate chain

Note: all the following commands must issue in privileged mode (use sudo in Ubuntu and Mac)

Preparing the CA:

Preparing Server certificate (private key included):

finally it’s time to create client cert (similar to server cert):

NGNIX in a Dockerfile

The best way to deploy NGINX is in container with Docker, so let’s prepare a directory with this files:

  • Dockerfile
  • server.key
  • server.crt
  • ca.crt
  • nginx.conf

Here the content of my Dockerfile for NGINX:

The complete Dockerfile could be downloaded here: https://github.com/linoproject/blog/blob/master/nginx_certificate/Dockerfile

NGINX config file explained

NGINX in the config file requires an instruction to “force” pairing certificate: ssl_verify_client. Check the official documentation for availabe instructions/options.

Here is the instructions for server section:

Note: the FQDN of the service must be specified in in the server_name instruction; in this case you must substitute “test.local” with your site.

You could find the full ngnix.conf here: https://github.com/linoproject/blog/blob/master/nginx_certificate/nginx.conf

An example with a backend

To complete the proxy chain a backend service must be instantiated linking with the nginx container. In my example I’m using a simple webserver container ( from linoproject/web_apachephp_mysql image ) which has a simple html file that expose my test service. So the compose file looks like this:

Here the complete file: https://github.com/linoproject/blog/blob/master/nginx_certificate/docker-compose.yml

A test with curl

To test the correct functionality you could simply use curl after the creation of pkcs12 certificate chain including private key and certificate. In the curl option, after certificate file indication, you must specify the certificate passphrase you’ve used during client certificate preparation.

Now it’s time to build your mobile application.

That’s all folks! Enjoy

Sources

http://nategood.com/client-side-certificate-authentication-in-ngi

http://nginx.org/en/docs/http/ngx_http_ssl_module.html

Salva