Basic HTTP Authentication With Nginx

Want to support HowtoForge? Become a subscriber!
 
Submitted by falko (Contact Author) (Forums) on Wed, 2011-09-14 17:04. :: Web Server | nginx

Basic HTTP Authentication With Nginx

Version 1.0
Author: Falko Timme <ft [at] falkotimme [dot] com>
Follow me on Twitter
Last edited 09/01/2011

This tutorial shows how you can use basic HTTP authentication with Nginx to password-protect directories on your server or even a whole website. This is the Nginx equivalent to basic HTTP authentication on Apache with .htaccess/.htpasswd.

I do not issue any guarantee that this will work for you!

 

1 Preliminary Note

I'm using the website www.example.com here with the document root /var/www/www.example.com/web/ and the Nginx vhost configuration file /etc/nginx/sites-enabled/www.example.com.vhost. The directory I want to password-protect is /var/www/www.example.com/web/test/.

 

2 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.

 

2.1 Using Apache's htpasswd Command

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

which htpasswd

root@server1:~# which htpasswd
/usr/bin/htpasswd
root@server1:~#

If you get an output like the one above, everything is fine - htpasswd is already installed. 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:

apt-get install apache2-utils

I want to create the password file /var/www/www.example.com/.htpasswd now and store the user falko 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 -c /var/www/www.example.com/.htpasswd falko

You will be asked for a password for the user falko. 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:

htpasswd /var/www/www.example.com/.htpasswd till

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

 

2.2 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:

cd /usr/local/bin
wget http://trac.edgewall.org/export/10791/trunk/contrib/htpasswd.py
chmod 755 /usr/local/bin/htpasswd.py

I want to create the password file /var/www/www.example.com/.htpasswd now and store the user falko 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 falko falkossecret

Please replace falkossecret with a password for the user falko. 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:

htpasswd.py -b /var/www/www.example.com/.htpasswd till tillssecret

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

 

3 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.vhost, inside the server {} container.

vi /etc/nginx/sites-enabled/www.example.com.vhost

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 / {}):

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;
       }
[...]
}

Reload Nginx afterwards:

/etc/init.d/nginx reload

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:

 

4 Links

 

About The Author

Falko Timme is the owner of Boost Your Site mit Timme Hosting - ultra-schnelles nginx-WebhostingTimme Hosting (ultra-fast nginx web hosting). He is the lead maintainer of HowtoForge (since 2005) and one of the core developers of ISPConfig (since 2000). He has also contributed to the O'Reilly book "Linux System Administration".


Please do not use the comment function to ask for help! If you need help, please use our forum.
Comments will be published after administrator approval.
Submitted by Anonymous (not registered) on Tue, 2013-01-01 22:07.

this is working :)

Can we add a logout buttion?

 

Submitted by Virginie (not registered) on Wed, 2012-08-22 16:14.

Hello,

I tried this solution and it works well, but I put the path of a test directory's file (http://www.example.com/test/test.php), the prompt windows doesn't show.

Do you know how to make this rule recursive for all the test directory's content ?

Thanks :)

 

Submitted by Anonymous (not registered) on Tue, 2012-01-31 12:42.

Your example doesn't work for files under /test/

 

Submitted by Karl (not registered) on Tue, 2013-01-15 11:06.

Its easy.. just replace

location /test
with:
location ^~ /test 
Submitted by abdi (registered user) on Mon, 2013-07-08 06:48.
Hello Everybody,

I need some help ...
Currently I am allowing authentication to the /administrator folder by (and this working fine for me):

location /administrator {
<tmpl_var name='web_document_root_www_proxy'>
index index.html index.php;
auth_basic "Members Only";
auth_basic_user_file <tmpl_var name='stats_auth_passwd_file'>;
}

However, the problem with that is if a user installs say Joomla in a subfolder within root eg

/joomla/ then that setting does not take effect.

I would like to take effect to any administrator folder accessed via the web regardless of the folder level .

Ie,

www.domain.com/administrator
www.domain.com/joomla/administrator
www.domain.com/joomla/site2/administrator

and etc ..

ALL those should be authenticated based on my .htaccess file defined above.

Please advice me on how I can modify the above directive to support that ...