NGINX
NGINX with RapID
In order to use NGINX with RapID, you will need to configure 2 web servers.
This is due to the limitation of NGINX not allowing the configuration of 1way/2 way TLS per channel.
- web server will be one way TLS (Your Registration web service)
- web server will be two way TLS (Your Authentication web service)
Details on how to configure one way and two way TLS for NGINX are below.
Setting up one way TLS with a Self-Signed Server Certificate on Linux (NGINX)
A Self-Signed Server Certificate should be used for Test purposes only.
This procedure generates a self-signed certificate that does not originate from a generally trusted source; therefore, you should not use this certificate to help secure data transfers between Internet clients and your server.
Create the Self-Signed Certificate
Create a directory that will be used to hold all of your SSL information. This can be created under the Nginx configuration directory:
sudo mkdir /etc/nginx/ssl
Now that you have a location to place your files, you can create the SSL key and certificate files in one motion by typing:
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/nginx/ssl/nginx.key -out /etc/nginx/ssl/nginx.crt
The commands used are below:
- openssl: This is the basic command line tool for creating and managing OpenSSL certificates, keys, and other files.
- req: This subcommand specifies that we want to use X.509 certificate signing request (CSR) management. The "X.509" is a public key infrastructure standard that SSL and TLS adheres to for its key and certificate management. We want to create a new X.509 cert, so we are using this subcommand.
- -x509: This further modifies the previous subcommand by telling the utility that we want to make a self-signed certificate instead of generating a certificate signing request, as would normally happen.
- -nodes: This tells OpenSSL to skip the option to secure our certificate with a passphrase. We need Nginx to be able to read the file, without user intervention, when the server starts up. A passphrase would prevent this from happening because we would have to enter it after every restart.
- -days 365: This option sets the length of time that the certificate will be considered valid. We set it for one year here.
- -newkey rsa:2048: This specifies that we want to generate a new certificate and a new key at the same time. We did not create the key that is required to sign the certificate in a previous step, so we need to create it along with the certificate. The rsa:2048 portion tells it to make an RSA key that is 2048 bits long.
- -keyout: This line tells OpenSSL where to place the generated private key file that we are creating.
- -out: This tells OpenSSL where to place the certificate that we are creating.
These options will create both a key file and a certificate. You will be asked a few questions about our server in order to embed the information correctly in the certificate.
Fill out the prompts appropriately. The most important line is the one that requests the Common Name (e.g. server FQDN or YOUR name).
You need to enter the domain name that you want to be associated with your server.
You can enter the public IP address instead if you do not have a domain name.
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:New York
Locality Name (eg, city) []:New York City
Organization Name (eg, company) [):Example Inc.
Organizational Unit Name (eg, section) []:Example Org
Common Name (e.g. server FQDN or YOUR name) []:your_domain.com
Email Address []:admin@your_domain.com
Both of the files you created will be placed in the /etc/nginx/ssl directory.
Configure NGINX to Use SSL
You have created your key and certificate files under the NGINX configuration directory. Now we just need to modify our NGINX configuration to take advantage of these by adjusting our server block files.
NGINX versions 0.7.14 and above (Ubuntu 14.04 ships with version 1.4.6) can enable SSL within the same server block as regular HTTP traffic. This allows you to configure access to the same site in a much more succinct manner.
Your server block may look something like this:
server {
listen 80 default_server;
listen [::]:80 default_server ipv6only=on;
root /usr/share/nginx/html;
index index.html index.htm;
server_name your_domain.com;
location / {
try_files $uri $uri/ =404;
}
}
The only thing we would need to do to get SSL working on this same server block, while still allowing regular HTTP connections, is add a these lines:
server {
listen 80 default_server;
listen [::]:80 default_server ipv6only=on;
listen 443 ssl;
root /usr/share/nginx/html;
index index.html index.htm;
server_name your_domain.com;
ssl_certificate /etc/nginx/ssl/nginx.crt;
ssl_certificate_key /etc/nginx/ssl/nginx.key;
location / {
try_files $uri $uri/ =404;
}
}
When you are finished, save and close the file.
Now, all you have to do is restart NGINX to use your new settings:
sudo service nginx restart
This should reload your site configuration, now allowing it to respond to both HTTP and HTTPS (SSL) requests.
Test your Setup
Your site should now have SSL functionality.
Test http access - In your web browser, go to your server's domain name or IP address:
http://server_domain_or_IP
You should see your website. In this example below it’s just serving the default NGINX page:
Check that the server can use SSL to communicate. Do this by specifying the https protocol instead of the http protocol.
https://server_domain_or_IP
You will likely get a warning in your web browser that looks something like this:
This is expected. It is telling you that it cannot verify the identity of the server you are trying to connect to because it isn't signed by a certificate authority that the browser has been configured to trust. This expected as a self-signed certificate was used.
Click on "Proceed anyway". You should see your site again:
Setting up two way TLS with a Self-Signed Server Certificate on Linux (NGINX)
Configure one way TLS on your webserver first.
Download the trusted issuer certificate file from your RapID Customer Dashboard to a location on your webserver. e.g. /etc/nginx/ssl
Open the NGINX virtual host file for the website you are securing.
sudo nano /etc/nginx/sites-available/default
ssl_client_certificate /etc/nginx/ssl/ trusted_issuer_certificate.cer;
ssl_verify_client on;
Restart NGINX to use your new settings:
sudo service nginx restart
Test the connection by going to - https://server_domain_or_IP
You should see the following, this is expected as no client certificate was provided when trying to access the site.
PHP configuration using php5-fpm
On linux the simplest and quickest way to enable php with NGINX is by using php5-fpm.
You can get php5-fpm using apt-get on Ubuntu.
sudo apt-get php5-fpm
Uncomment the following lines in the configuration file /etc/nginx/sites-available/default and
/etc/nginx/sites-enabled/default.
location ~ \.php$ {
fastcgi_split_path_info ^(.+\.php)(/.+)$;
# NOTE: You should have "cgi.fix_pathinfo = 0;" in php.ini
# # With php5-cgi alone:
# fastcgi_pass 127.0.0.1:9000;
# With php5-fpm:
fastcgi_pass unix:/var/run/php5-fpm.sock;
fastcgi_index index.php;
include fastcgi_params;
}
For two way TLS add the following lines into the php section in the configuration file /etc/nginx/sites-enabled/default.
fastcgi_param HTTPS 'on';
fastcgi_param SSL_CLIENT_NGINX_DN $ssl_client_s_dn;
Please ensure the variable is called SSL_CLIENT_NGINX_DN.
The php section in /etc/nginx/sites-enabled/default should now look something like:
location ~ \.php$ {
fastcgi_split_path_info ^(.+\.php)(/.+)$;
# NOTE: You should have "cgi.fix_pathinfo = 0;" in php.ini
fastcgi_param HTTPS 'on';
fastcgi_param SSL_CLIENT_NGINX_DN $ssl_client_s_dn;
# With php5-cgi alone:
#fastcgi_pass 127.0.0.1:9000;
# With php5-fpm:
fastcgi_pass unix:/var/run/php5-fpm.sock;
fastcgi_index index.php;
include fastcgi_params;
}