====== Ubuntu - NginX - Basic Authentication ======

This is the Nginx equivalent to basic HTTP authentication on Apache with .htaccess /.htpasswd.

----

===== Creating the Password File =====

We need a password file where users that should be able to log in are listed with their passwords (in encrypted form).

To create such a password file, we can either use Apache's htpasswd tool, or we use the Python script from http://trac.edgewall.org/browser/trunk/contrib/htpasswd.py.

----

===== Using Apache's htpasswd Command =====

If you want to use Apache's htpasswd command, check if it exists on your system:

<code bash>
which htpasswd
</code>

Will return something like this is the htpassed command exists on the system.

<code bash>
/usr/bin/htpasswd
</code>


If the command returns without any output, htpasswd does not exist on your system, and you must install it.

On Debian/Ubuntu, it's part of the **apache2-utils** package which we can install as follows:

<code bash>
sudo apt install apache2-utils
</code>


Create the password file /var/www/www.example.com/.htpasswd now and store the user john in it (you can give the password file any name you like - it's not necessary to name it .htpasswd; 

For example, I just named it .htpasswd because that's the way password files are named under Apache:

<code bash>
htpasswd -c /var/www/www.example.com/.htpasswd john
</code>

You will be asked for a password for the user john.

Please note that the -c switch makes that the file is created from scratch; if it didn't exist before, it will be created; if it existed before, it will be overwritten with a new one, and all users from the old file will be lost!

Therefore, if you want to add another user without deleting all existing users, use the htpasswd command without the -c switch:

<code bash>
htpasswd /var/www/www.example.com/.htpasswd jack
</code>

The last command adds the user jack to /var/www/www.example.com/.htpasswd so that we now have the users john and jack in it.

----

===== Using the htpasswd.py Python Script =====

If you don't want to or cannot use Apache's htpasswd command, you can use the Python script from http://trac.edgewall.org/browser/trunk/contrib/htpasswd.py.

We download it to /usr/local/bin and make it executable as follows:

<code bash>
cd /usr/local/bin
wget http://trac.edgewall.org/export/14464/trunk/contrib/htpasswd.py
chmod 755 /usr/local/bin/htpasswd.py
</code>

Create the password file /var/www/www.example.com/.htpasswd now and store the user john in it (you can give the password file any name you like - it's not necessary to name it .htpasswd; I just named it .htpasswd because that's the way password files are named under Apache):

htpasswd.py -c -b /var/www/www.example.com/.htpasswd john johnssecret

Please replace johnssecret with a password for the user john.  Please note that the -c switch makes that the file is created from scratch; if it didn't exist before, it will be created; if it existed before, it will be overwritten with a new one, and all users from the old file will be lost! Therefore, if you want to add another user without deleting all existing users, use the htpasswd.py command without the -c switch:

<code bash>
htpasswd.py -b /var/www/www.example.com/.htpasswd jack jackssecret
</code>

The last command adds the user jack to /var/www/www.example.com/.htpasswd so that we now have the users john and jack in it.

----

===== Configuring Nginx =====

Now that we have our password file in place, we just need to add it to our Nginx vhost configuration in /etc/nginx/sites-enabled/www.example.com, inside the server {} container.


<code bash>
vi /etc/nginx/sites-enabled/www.example.com
</code>

Because I want to password-protect the test directory in the document root, I use location /test {} here (to password-protect the whole website, you'd use location / {}):

<file bash /etc/nginx/sites-enabled/www.example.com>
server {
       listen 80;
       server_name www.example.com example.com;
       root /var/www/www.example.com/web;
[...]
       location /test {
                auth_basic "Restricted";
                auth_basic_user_file /var/www/www.example.com/.htpasswd;
       }
[...]
}
</file>

----

===== Reload Nginx =====

<code bash>
service nginx reload
</code>

That's it!

You can now go to your test directory in a browser (http://www.example.com/test), and you should be asked for a username and password:

If you enter the correct username and password, you'll be granted access.

Otherwise, you will see a **401** Authorization Required error message.