Web server administrators, system administrators, and web developers may all play a role in installing an SSL Certificate on an Nginx web server. These instructions will attempt to provide guidance for those.
I. Create a CSR with OpenSSL
To create a CSR with openssl, run the following command:
openssl req -newkey rsa:4096 -keyout key.pem -out req.pem -nodesThis is a basic example that you can use in most cases for creating your CSR. For more details on a CSR (Certificate Signing Request) and other ways to generate it, visit our post titled Certificate Signing Request. This post will go into more details on what a CSR is and more advanced options when using OpenSSL to create it.
Note that you MUST save your private key as it will be used when installing your SSL certificate in a later step. The CSR can be thrown away after submitting it to the CA you choose. If you would like, you may keep and reuse the CSR when renewing your certificate later, but we recommend always generating a new one.
After creating your CSR, you will then submit it to the CA (Certificate Authority) you will be buying your certificate from. The SSL Store is the company we recommend buying your certificate from and gives you a multitude of CAs and certificates to choose from. After submitting your CSR to them, they should issue your certificate quickly. Then you will be ready to proceed with installing your certificate in Nginx.
II. Install the issued certificate in Nginx
To install your newly purchased SSL certificate, make sure that the end entity certificate issued to you contains the intermediate certificates as well. In other words, your .pem file should contain first your server certificate followed by the intermediate certificates, and SHOULD NOT contain the root certificate. If it does contain the root, the configuration will continue to work but it is not a recommended practice since the clients visiting your site should already have the root in their trust store.
For an example on creating the pem file if the issued certificate does not already come bundled in one file with its intermediates, use this command to guide you:
cat example.com.pem intermediate1.pem intermediate2.pem >> example.com_with_chain.pemOpen the Nginx virtual host file with your preferred editor (we recommend vi), and add the following lines to the file, inside of the server block:
ssl on;
ssl_certificate example.com_with_chain.pem
ssl_certificate_key key.pemNote that the ssl_certificate is the file we created in the previous step, containing the end entity server certificate along with the intermediate certificates. The nginx ssl_certificate property contains the server certificate bundled with the certificate chain, and note that the server certificate MUST come before the intermediate chain. There is NOT an alternate option to specify the chain separately. The key.pem file is the private key that was created along with your CSR.
The private key may also be stored in the same file with the ssl certificate, but we generally recommend against this approach for the simple reason that it’s explicit to keep the key separate along with its permissions. If you encounter the following error, you know you have placed the key in the wrong order in the certificate file.
SSL_CTX_use_PrivateKey_file(" ... key.pem") failed
(SSL: error:0B080074:x509 certificate routines:
X509_check_private_key:key values mismatch)Additionally, the nginx ssl_protocols property may be specified to restrict the ssl connection over specific tls versions. The following example will restrict to TLS versions, not allowing the former SSL versions.
ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3The nginx ssl_ciphers property may be specified to limit the available ciphers. By default, nginx ssl_ciphers property is set to ssl_ciphers HIGH:!aNULL:!MD5.
III. Restart Nginx after installing your SSL certificate
A restart of your Nginx web server is necessary to pick up the new SSL configuration. Note that the server OS (Operating System) does not need to be rebooted, only your instance of Nginx. To restart Nginx, run the following command:
sudo /etc/init.d/nginx restartAfter the restart, your site should now be protected and identified by the SSL certificate you installed.
IV. Verification and Troubleshooting Nginx SSL
To verify your SSL configuration on your Nginx web server you can do a couple of things.
- Visit your website from a browser and check the installed SSL certificate, as well as whether or not the website is served from https. If there is an SSL error or misconfiguration, your browser will deliver that error to you.
- Check your SSL configuration with our SSL Tools. Our tools include an SSL Certificate Decoder as well as an SSL checker to troubleshoot your SSL details.
Most configuration problems come down to the certificate chain not being installed correctly. Again, make sure to include the end entity server certificate as well as the chain in the same file.
Nginx SSL configuration with docker
To provide a simple example of configuring SSL and SSL certificates with Nginx, let’s spin up a quick docker instance to demonstrate how to do so. This is meant simply for an educational exercise and is by no means a complete production ready example, but will cover the basics to get you started.
- Create a new directory:
mkdir nginx-docker; cd nginx-docker- Create a new file named nginx.conf. The files contents should be the following for docker nginx ssl on localhost:
events { }
http {
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
server_name localhost;
return 200;
}
server {
listen 443 ssl;
server_name localhost;
ssl_certificate /ssl/cert.pem;
ssl_certificate_key /ssl/key.pem;
access_log /var/log/nginx/data-access.log combined;
}
}- Create a directory named ssl and move your cert.pem and key.pem files into it. Note that cert.pem should be formatted as described earlier in this article. If your SSL certificate and private key files are named differently, then make sure to update the nginx.conf file accordingly.
- Create the docker-compose.yml file. It’s contents should be as follows:
version: '3.8'
services:
nginx:
image: nginx
ports:
- "80:80"
- "443:443"
volumes:
- /home/misterpki/nginx-docker/nginx.conf:/etc/nginx/nginx.conf
- /home/misterpki/nginx-docker/ssl:/ssl- Run docker-compose to spin up the Nginx instance with your SSL certificate installed and configured.
docker-compose up --buildNote that in this example, a self-signed certificate is being used that has a CN different than localhost, so you will see browser warnings. For one, the certificate is not trusted by the OS (Operating System) certificate store. Secondly, the CN does not match the host name. When using a publicly trusted certificate issued to your domain, you should not see any SSL Certificate errors.
For the full example, visit our GitHub repo containing the files to run the docker example of Nginx and SSL certificates. Docker nginx ssl certificates.
Conclusion
We hope to have covered in full how to successfully install an SSL certificate on an Nginx web server. If you have any questions suggestions on how to improve this article please leave us a comment. If you need assistance on troubleshooting your SSL installation or need help finishing, send us an email at info@misterpki.com.
Leave a Reply