how to configure basic authentication in nginx

How To Configure Basic Authentication in NGINX

Last updated on July 4th, 2024 at 06:13 am

NGINX allows you to configure basic HTTP authentication on your website which allows you to restrict access to one or more pages on your website using a simple username/password. You can use this method to secure http, server or even location blocks. You can use it to secure virtual hosts, websites, or sensitive pages of your website such as admin pages. In this article, we will look at how to configure basic authentication in NGINX.

What is Authentication in NGINX

By default, when you run a site on NGINX, all users can access all its pages unless their access is controlled. Many administrators use firewall rules or Allow/Deny server directives to restrict access to one or more web pages on their site, in case it contains sensitive information. But anyone can access these pages from those IP addresses that are allowed access. So how to add an extra layer of security? NGINX allows you to password protect one or more web pages on your website.

Why Do You Need Basic Authentication

By default, all web pages on your website are publicly accessible via NGINX. Often website administrators may need to protect web pages with sensitive information from public access. In such cases, it is advisable to add an extra layer of security by enabling basic authentication for those web pages. Once this is done, when a user requests access to web page with basic authentication, they will be asked for username & password to proceed further. This basic authentication allows site admins to selectively control access to certain critical web pages, without affecting other pages. Also, it does not require any coding so they do not have to depend on the web development team.

How To Configure Basic Authentication in NGINX

Here are the steps to configure basic authentication in NGINX.

1. Install Apache Utils

We need to use htpasswd utility to set up basic authentication. For that, we need to install apache2-utils or httpd-tools. Open terminal and run the following command

# yum install httpd-tools [RHEL/CentOS] 
$ sudo apt install apache2-utils [Debian/Ubuntu]

2. Create User/Password

Next, run htpasswd command to create a user that will be given access to your website.

# htpasswd -c /etc/nginx/conf.d/.htpasswd developer

We use -c option to specify password file location. When you press enter, you will be prompted for a password.

For example, when we create another user, we don’t specify password file location.

# htpasswd /etc/nginx/conf.d/.htpasswd developer2

This file contains a list of user credentials who will be allowed access to your password protected web pages. By modifying its contents, you can control which user can access your web pages.

3. Backup Files

We need to modify NGINX configuration file or virtual host file, whichever you have access to. So it is essential to take a backup of these files before you edit it.

$ sudo cp /etc/nginx/nginx.conf /etc/nginx/backup-nginx.conf
$ sudo cp $ sudo vi /etc/nginx/sites-enabled/website.conf /etc/nginx/sites-enabled/backup-website.conf

4. Open NGINX configuration file

Open terminal and run the following command to open NGINX server configuration file.

$ sudo vi /etc/nginx/nginx.conf

If you have configured separate virtual hosts for your website (e.g, such as /etc/nginx/sites-enabled/website.conf then open its configuration with the following command

$ sudo vi /etc/nginx/sites-enabled/website.conf

Alternatively, you can also open the default virtual host configuration file.

$ sudo vi /etc/nginx/sites-enabled/default

5. Password Protect NGINX

In order to password protect your website, or certain web pages, we need to use auth_basic and auth_basic_user_file directives in NGINX server configuration.

Password Protect All Servers

For example, if you want to configure basic authentication for all virtual hosts (an entire http block), add the above two directives as shown below in http block.

   auth_basic "Restricted Access!"; 
   auth_basic_user_file /etc/nginx/conf.d/.htpasswd;

In the above code, we specify the path of password file in auth_basic_user_file directive and message to be displayed in auth_basic directive.

Password Protect Single website or server

Similarly, here’s the code to protect server block, that is, implement basic authentication for website or domain.

    auth_basic "Restricted Access!";
    auth_basic_user_file /etc/nginx/conf.d/.htpasswd;

Password protect a directory

You can also configure basic authentication for specific web pages/subdirectories (e.g /admin) by adding auth_basic and auth_basic_user_file directives in a location block.

location /admin/ {
    auth_basic "Restricted Access!";
    auth_basic_user_file /etc/nginx/conf.d/.htpasswd;

Protect Single URL

You can also do this for a single URL. Just add the auth_basic and auth_basic_user_file directive for location block of URL.

location /login.php {
auth_basic "Restricted Access!";
auth_basic_user_file /etc/nginx/conf.d/.htpasswd;

Please note, you do not need to use the same password file for every auth_basic_user_file directive. you can always create multiple password files in step #2. Once you do this, you can pick and choose the appropriate file for each auth_basic_user_file. This provides a powerful way to control user access, without any coding or updating firewall rules.

6. Restart NGINX Server

Run the following command to check syntax of your updated config file.

$ sudo nginx -t

If there are no errors, run the following command to restart NGINX server.

$ sudo service nginx reload #debian/ubuntu
$ systemctl restart nginx #redhat/centos

7. Verify basic authentication

Open browser and visit the URL (e.g that you have protected. You should see an authentication screen as the one below.


In this article, we have learnt how to enable basic authentication in NGINX server. You can use this to configure password protection for one or more web pages on your site. It is a very useful way to block unauthorized access on your website. It does not require any coding. Once you have enabled basic authentication, you can easily add, remove or modify user credentials in .htpasswd file and control which users have access to your web pages. You can create multiple password files to compartmentalize users and choose the appropriate file for each auth_basic_user_file server directive. This makes it easy to manage user access without any coding or firewall rules.

Ubiq makes it easy to visualize data, and monitor them in real-time dashboards. Try Ubiq for free.

Also read :
How to Install Let’s Encrypt on NGINX
How to Enable GZIP Compression in NGINX
How to Limit Download Speed in NGINX
How to Create Custom 404 page in NGINX
Redirect vs Rewrite in NGINX