Table of Contents
In this guide we'll see how we can implement a password-based authentication mechanism on our NGINX web servers using HTTP Basic Authentication: a simple auth method that allows webmasters to force their visitors to input a username and password combination before allowing a HTTP request, even if they are not registered on the website or if the website doesn't have a login feature at all.
Since we'll store these usernames and password into a credential storage file, in order to implement such method we're going to need a password file creation tool, such as apache2-utils.
Install apache2-utils
The first thing we need to do is to install apache2-utils, a neat tool that provides some add-on programs useful for any web server (not necessarily apache-specific). In a typical Ubuntu environment, such tool can be installed using APT by issuing the following console command:
|
1 |
sudo apt install apache2-utils |
The tool has a total weight of 400kb and will provide you with a lot of useful console commands, including the one we need: htpasswd, which can be used to create encrypted credential storage files.
Create the credential storage file
Now we have to create the credential storage file, together with our first user. Before doing that, we need to choose:
- a suitable folder (such as /etc/nginx/auth)
- the file name (such as default.htpasswd)
- our first basic authentication user (such as myuser)
The folder should be created beforehand using the mkdir command: once done, we can issue the following command to create the /etc/nginx/auth/default.htpasswd file with the myuser user within it:
|
1 |
sudo htpasswd -c /etc/nginx/auth/default.htpasswd myuser |
The tool will then prompt us for a password, which will be hashed and stored within the file.
Once done, we can proceed to configure it in NGINX.
Configure NGINX
To implement our new credential storage file (and user) in NGINX, we need to open the configuration file that controls the location that we're going to protect: this can be /etc/nginx/nginx.conf file, one of the many configuration files present in the /sites-enabled/ folder, or a completely diffenent file, depending on your specific scenario and NGINX build.
Here's how the file should look like:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name mywebsite.com; # ... some stuff ... location / { # ... some stuff ... } } |
And here's what we needd to add within the location block:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name mywebsite.com; # ... some stuff ... location / { auth_basic "Password protected location"; auth_basic_user_file /etc/nginx/auth/default.htpasswd; # ... some stuff ... } } |
As we can see from the marked lines, we've specified the auth_basic directive and gave a name to the password-protected area: the name of the area will be shown in the username/password dialog window when asking for credentials (if the browser supports such feature); then we've used the auth_basic_user_file directive to tell NGINX where to retrieve the credential storage file in order to properly validate the user's input.
That's it: now the browser will prompt our users with a username & password request before making them able to access the resource(s) available through that location. The users who will insert a wrong username/password combination will receive a 401 Unauthorized HTTP error.
Security considerations
HTTP Basic Authentication is a handy feature, but it's very important for System Administrators to understand its weak points in terms of security, especially in a non-HTTPS context. Here are a couple guides that we strongly suggest to read before implementing it:
- Basic Authentication over HTTP: known vulnerabilities (source: Acunetix)
- Is Basic Authentication secure if done over HTTPS? (source: Stack Exchange)
Conclusion
That's it, at least for now: we hope that this simple guide will help other System Administrators that are looking for a way to implement HTTP Basic Authentication on their NGINX web servers.
