Restricting Access with HTTP Basic Authentication

It is very common practice to restrict your development environment with some sort of username/password authentication so that the visitors has to authenticate first before landing into the website. For this purpose, HTTP basic authentication comes really handy, it is a simple response mechanism with which a server can request authentication information (userId and password) from a client, if the client provides correct credentials then the server serves the protected content otherwise sends authorization error with 401 status code.

Lets get started

Prerequisites

• NGINX
• apache2-utils as a password creation utility

Step 1 - Create a Password File

Creating a password file with a first user user1. Run the htpasswd utility with the -c flag to create a new file. The first argument contains the file path and second one holds the name of the user:

$ sudo htpasswd -c /etc/nginx/.htpasswd user1

You will be asked to supply and confirm a password for the user.

Leave out -c flag incase you wish to add multiple users:

$ sudo htpasswd /etc/nginx/.htpasswd user2

You can confirm that the file contains paired username and encrypted passwords:

$ cat /etc/nginx/.htpasswd 

# Output
user1:$apr1$PbDKFyTU$1mPXhE3Yjbygmg5AH5hNE.
user2:$apr1$u/3QM/YL$jVhMow7XyR.umwpRcNdKE0

Step 2 - Configure NGINX HTTP Basic Authentication

Now that you have a file with all users and passwords in an encrypted format that the server can read, the next step would be configuring the server to check this file before serving the protected content.

To start configuring the server, you would like to find out where does the server configuration is located, this would help you:

$ cat /etc/nginx/nginx.conf

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    #...

    include /etc/nginx/conf.d/*.conf;
}

In above example, all the configurations are located inside /etc/nginx/conf.d/ directive.

Lets check the configuration files inside this directive:

$ ls /etc/nginx/conf.d/*.conf

default.conf  my_proxy.conf

In above example, it shows that there are two configuration files inside /etc/nginx/conf.d/ directive, one is default.conf and another is my_proxy.conf.

After finding out the correct configuration file, lets begin editing the server configuration and specifying the auth_basic which is a name for the protected area and auth_basic_user_file is a directive with a path to the .htpasswd file that contains user/password pairs.

$ sudo nano /etc/nginx/conf.d/default.conf

server {
    listen 80 default_server;
    server_name example.com;

        #....
        location / {

        }
}

Lets add basic authentication:

server {
    listen 80 default_server;
    server_name example.com;

        #....
    location / {
                # add http basic authentication 
                auth_basic "Password Required";
                auth_basic_user_file /etc/nginx/.htpasswd;
    }
}

Step 3 - Testing the Setup

This ends with your server configuration, restart your server to apply the changes:

$ sudo service nginx reload

When everything goes alright, your are prompted to log in when you load your site:

If the provided username and password do not match the password file, you get the 401 Authorization Required error.

Conclusion

You have just implemented HTTP basic authentication on NGINX. More detailed information about different means of access restrictions are available in NGINX Documentation.