How to Password Protect a File or Directory on Nginx

It’s not uncommon the need to protect some content on a webserver, you might want to protect some client’s content, for example, but you don’t have, or want, a webapp and all the burden to implement an app level authentication. Hopefully, Nginx provides a very simple way to protect files and directories using HTTP Authentication.

Step 1. Installing Apache’s apache2-utils

I know what you might be thinking: “What? I’m not using Apache, I’m using Nginx!”. Dont’ worry, I know! To use HTTP Authentication, Nginx needs a file which stores the username and encrypted password, and htpasswd, an Apache utility inside apache2-utils package, is the easiest way to do that, although there are alternatives. Don’t worry, you’re not installing the whole Apache package, just the apache2-utils one. You can click here to see more information about that package on Debian (probably the same package for Ubuntu).

If you’re on Mac OSX, Apache already comes installed, so you can skip to the next step. If you’re on a Linux system (Debian or Ubuntu), and it doesn’t have Apache installed, install apache2-utils running:

$ sudo apt-get install apache2-utils

Step 2. Creating a User and Password

Now let’s create the user and password in a new file:

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

In that example we’re creating a .htpasswd file at Nginx’ root directory (that’s default Debian / Ubuntu Nginx location, if you’re on a different system don’t forget to point to the right directory). You can choose any name and location for your file, but do not put it in a web-accessible location! We’re also adding the user_a to it. Next you should be asked to put the password.

You can store any number of user/password to a single file. To do that you just need to omit the -c flag. If you do so, though, any valid user will be able to see any protected content. So you can have more security if you store one (or a couple) users for each content you’re protecting. That’s because when you protect a content, you tell Nginx to look at some file for valid users, as you’ll see next. So any user in that file will be able to see any content that points to that file. If you have several protected URLs for different clients, and you want them to see only their content, you should create one file and one user / password for each client (in this case you can change “.htpasswd” file name by something like “.my-client-auth”).

Step 3. Setting up Nginx

Now you need to add some simple configuration to your website’s configuration file, inside the server {} block.

If you want to protect a directory:

location ^~ /my-protected-directory {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
    index  index.html index.htm;

That will protect all files and directories within the directory path you provided.

If you want to protect a single file:

location ^~ /my-directory/my-file.html {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
    index  index.html index.htm;

Don’t forget to change the path of your .htpasswd file in the auth_basic_user_file directive.

Now you just need to restart Nginx so your changes can take effect.

Step 4. Restarting Nginx

$ sudo /etc/init.d/nginx restart

Don’t forget to change your Nginx installation path if you’re not on Ubuntu / Debian.

Now when you visit your protected content your browser should prompt you a username and password.

Deleting a User

If you want to delete a user from a file, just run:

$ sudo htpasswd -D /etc/nginx/.htpasswd user_a

Where /etc/nginx/.htpasswd is the path of your file and user_a is the user to be removed.

How to Install Nginx – Tutorial (Ubuntu / Debian)
How to Configure a Website on Nginx and Linux – Tutorial
How to Securely Set Up a VPS Server – Tutorial (Ubuntu / Debian)

Nginx HttpAuthBasic Module
Basic access authentication (Wikipedia)
HTTP Authentication: Basic and Digest Access Authentication (IETF)

Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.

comments powered by Disqus