Configure HTTP Basic Authentication on NGINX How to implement HTTP Basic Authentication in a NGINX web server to restrict access for your website users with a simple username/password challenge

How to cache your website using NGINX and FastCGI in CentOS 7 with PHP FastCGI Process Manager PHP-FPM

In this guide we'll see how we can implement a password-based authentication mechanism on our NGINX web servers using HTTP Basic Authentication: a simple auth method that allows webmasters to force their visitors to input a username and password combination before allowing a HTTP request, even if they are not registered on the website or if the website doesn't have a login feature at all.

Since we'll store these usernames and password into a credential storage file, in order to implement such method we're going to need a password file creation tool, such as  apache2-utils.

HTTP Basic authentication can be combined with several other access restriction methods, such as IP address or geographical location filters.

Install apache2-utils

The first thing we need to do is to install apache2-utils, a neat tool that provides some add-on programs useful for any web server (not necessarily apache-specific). In a typical Ubuntu environment, such tool can be installed using APT by issuing the following console command:

The tool has a total weight of 400kb and will provide you with a lot of useful console commands, including the one we need: htpasswd, which can be used to create encrypted credential storage files.

Create the credential storage file

Now we have to create the credential storage file, together with our first user. Before doing that, we need to choose:

  • a suitable folder (such as /etc/nginx/auth)
  • the file name (such as default.htpasswd)
  • our first basic authentication user (such as myuser)

The folder should be created beforehand using the mkdir command: once done,  we can issue the following command to create the /etc/nginx/auth/default.htpasswd file with the myuser user within it:

The tool will then prompt us for a password, which will be hashed and stored within the file.

Once done, we can proceed to configure it in NGINX.

Configure NGINX

To implement our new credential storage file (and user) in NGINX, we need to open the configuration file that controls the location that we're going to protect: this can be /etc/nginx/nginx.conf file, one of the many configuration files present in the /sites-enabled/ folder, or a completely diffenent file, depending on your specific scenario and NGINX build.

Here's how the file should look like:

And here's what we needd to add within the location block:

If you want to limit access to the whole website with basic authentication, auth_basic and auth_basic_user_file need to be put in the Nginx configuration's server block; if we do this, we can still make some website areas public by setting the auth_basic directive to off for the specific location block(s) we want to keep open.

As we can see from the marked lines, we've specified the auth_basic directive and gave a name to the password-protected area: the name of the area will be shown in the username/password dialog window when asking for credentials (if the browser supports such feature); then we've used the auth_basic_user_file directive to tell NGINX where to retrieve the credential storage file in order to properly validate the user's input.

That's it: now the browser will prompt our users with a username & password request before making them able to access the resource(s) available through that location. The users who will insert a wrong username/password combination will receive a 401 Unauthorized HTTP error.

Security considerations

HTTP Basic Authentication is a handy feature, but it's very important for System Administrators to understand its weak points in terms of security, especially in a non-HTTPS context. Here are a couple guides that we strongly suggest to read before implementing it:


That's it, at least for now: we hope that this simple guide will help other System Administrators that are looking for a way to implement HTTP Basic Authentication on their NGINX web servers.

This post is part of a series of articles, tutorials and guides on the NGINX web server & reverse proxy. To read the other posts, click here!

About Ryan

IT Project Manager, Web Interface Architect and Lead Developer for many high-traffic web sites & services hosted in Italy and Europe. Since 2010 it's also a lead designer for many App and games for Android, iOS and Windows Phone mobile devices for a number of italian companies. Microsoft MVP for Development Technologies since 2018.

View all posts by Ryan

Leave a Reply

Your email address will not be published. Required fields are marked *

The reCAPTCHA verification period has expired. Please reload the page.

This site uses Akismet to reduce spam. Learn how your comment data is processed.