I'm available to deliver your SaaS MVP in a few weeks, full-stack with the new Next.js App Router. Accelerate Your MVP Launch Now.

How to password-protect content on Linux + Nginx

Learn how to password-protect files and directories on Linux + Nginx in 4 steps using HTTP Authentication.

Flavio Silva
Flavio SilvaMarch 3, 2015
How to password-protect content on Linux + Nginx
Image by Freepik

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.

Do not type the $ sign you see in the command examples in this article. That's just an indicator that you should run the command that follows it in your command line tool.

Step 1. Installing Apache's apache2-utils

I know what you're 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 macOS, 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.

Wildcard HTTPS on Linux + Let's Encrypt + Nginx
What are HTTPS, TLS certificates, and Let's Encrypt?
How to install Nginx on Linux
How to set up a website on Linux + Nginx
How to set up a Linux VPS

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

How to password-protect content on Linux + Nginx by Flavio Silva is licensed under a Creative Commons Attribution 4.0 International License.

Leave a comment using your GitHub account

© 2024 Flavio Silva