How to Password Protect Web Directories in Nginx?

In today's digital landscape, ensuring the security of web applications and sensitive data is of paramount importance. One effective way to enhance the security of your web directories is by implementing password protection. With password protection in place, you can restrict access to authorized users and safeguard your confidential information.

Nginx, a popular web server and reverse proxy, offers robust capabilities for securing web directories. By setting up basic authentication, you can prompt users to enter a username and password before accessing specific directories on your website.

In this tutorial, we will walk you through the process of password protecting web directories in Nginx. We'll cover the installation of Apache Utils, the creation of a password file, and the configuration of the Nginx server block to enforce password authentication. Additionally, we'll explore advanced options such as IP restriction and custom error pages.


Before we dive into password protecting web directories in Nginx, there are a few prerequisites you need to have in place −

  • Nginx Web Server  Ensure that you have Nginx installed and running on your server. If you haven't installed Nginx yet, you can follow the official Nginx documentation or the documentation provided by your operating system to set it up.

  • Basic Nginx Configuration Knowledge  Familiarize yourself with basic Nginx configuration concepts, including server blocks and directives. This will help you understand and modify the necessary configuration files to enable password protection.

Once you have these prerequisites in order, you're ready to proceed with setting up password protection for your web directories.

Setting Up Basic Authentication

To password protect web directories in Nginx, you need to set up basic authentication. This involves installing Apache Utils, creating a password file, and configuring the Nginx server block.

Installing Apache Utils

Before we begin, let's make sure we have the necessary tools installed. Apache Utils provides the htpasswd utility, which we'll use to generate password hashes.

  • Start by updating your system's package manager 

sudo apt update
  • Once the update is complete, install the Apache Utils package 

sudo apt install apache2-utils

With Apache Utils installed, we can proceed to create the password file.

Creating a Password File

The password file will store the username and password combinations for authentication. We'll use the htpasswd utility to generate the password hash for each user.

  • Create a new password file or update an existing one by running the following command 

sudo htpasswd -c /path/to/password/file username

Replace /path/to/password/file with the path where you want to store the password file, and username with the desired username.

  • You'll be prompted to enter and confirm the password for the user. The utility will generate a password hash and add it to the password file.

Note − If you're updating an existing password file, omit the -c flag to avoid overwriting the file.

Configuring Nginx Server Block

Now that we have our password file ready, we need to configure the Nginx server block to enable basic authentication for the desired web directory.

  • Open the Nginx configuration file in a text editor 

sudo nano /etc/nginx/nginx.conf
  • Locate the server block that corresponds to the web directory you want to protect. It's usually found within the server { ... } section.

  • Inside the server block, add the following directives within the location / { ... } block.

location / {
   auth_basic "Restricted Access";
   auth_basic_user_file /path/to/password/file;

Replace /path/to/password/file with the actual path to the password file created earlier.

The auth_basic directive sets the authentication realm, which will be displayed to users when prompted for credentials. Feel free to customize the realm to fit your application.

  • Save the configuration file and exit the text editor.

  • To apply the changes, restart the Nginx service 

sudo service nginx restart

With basic authentication set up, Nginx will now prompt users for a username and password when accessing the protected web directories. Make sure to test the authentication by accessing the website in a web browser and entering the appropriate credentials.

Advanced Authentication Configuration

In addition to basic authentication, Nginx provides advanced authentication mechanisms that offer more flexibility and control over access to web directories. Let's explore two commonly used methods: using a custom login form and integrating with an external authentication server.

Using a Custom Login Form

With a custom login form, you can create a more user-friendly authentication experience by designing a login page tailored to your application's branding. This method involves configuring Nginx to redirect unauthorized users to the login form and validating their credentials.

  • Create a login page  Design an HTML login form and save it as login.html in the directory you want to protect.

  • Update the Nginx configuration  Modify the server block that corresponds to the protected directory and add the following directives.

location / {
   error_page 401 =200 /login.html;
   auth_request /auth;
   auth_request_set $auth_status $upstream_status;
   error_page 403 =200 /login.html;

location = /auth {
   proxy_pass http://localhost:8000/auth;  # Replace with your authentication script endpoint
   proxy_pass_request_body off;
   proxy_set_header Content-Length "";
   proxy_set_header X-Original-URI $request_uri;

This configuration sets up a custom login page at /login.html and specifies the authentication script's endpoint.

  • Implement the authentication script  Develop a script in the language of your choice (e.g., PHP, Python) that handles the authentication logic. The script should verify the user's credentials and return an appropriate response code (200 for success, 401 for unauthorized).

  • Test the custom login form  Access the protected directory in a web browser. Nginx will redirect you to the custom login form. Enter valid credentials and verify that access is granted.

Integrating with an External Authentication Server

If you have an existing authentication server, you can integrate it with Nginx to handle user authentication. This method allows for centralized user management and authentication, making it easier to maintain and scale authentication across multiple applications.

  • Configure Nginx as a reverse proxy  Set up Nginx as a reverse proxy to forward authentication requests to the external authentication server.

  • Update the Nginx configuration  Modify the server block for the protected directory and add the following directives.

location / {
   proxy_pass http://auth-server;
   proxy_set_header Host $host;
   proxy_set_header X-Real-IP $remote_addr;
   proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   proxy_set_header X-Forwarded-Proto $scheme;
   proxy_set_header X-Original-URI $request_uri;

Replace http://auth-server with the URL of your external authentication server.

  • Implement authentication logic on the server  Configure the external authentication server to handle incoming requests, verify user credentials, and return an appropriate response to Nginx.

  • Test the integration  Access the protected directory in a web browser. Nginx will forward the authentication request to the external server. Ensure that the server responds with the correct authentication status and grants access accordingly.

Additional Considerations and Best Practices

To ensure the effectiveness and security of your password-protected web directories in Nginx, consider the following additional considerations and best practices 

Enabling HTTPS

Securing the transmission of data between the client and the server is crucial for protecting sensitive information, including usernames and passwords. Implement SSL/TLS encryption by obtaining and installing an SSL/TLS certificate on your Nginx server. This will enable HTTPS and provide a secure connection for users accessing the password-protected directories.

Securing Passwords

To enhance the security of user passwords, encourage users to choose strong, unique passwords and consider implementing additional measures such as password complexity requirements and periodic password expiration. Additionally, ensure that the password file or external authentication server where user credentials are stored is adequately protected against unauthorized access.

Monitoring and Logging

Implement comprehensive monitoring and logging mechanisms to track authentication attempts, identify potential security threats, and detect any suspicious activities. Regularly review access logs and error logs to identify and investigate any unauthorized access attempts or anomalies.

Regularly Update and Patch

Keep your Nginx server and associated software up to date with the latest security patches. Regularly check for updates and apply them promptly to address any security vulnerabilities and ensure that your server remains secure.

Access Control

Consider implementing additional access control measures such as IP whitelisting or blacklisting to further restrict access to the password-protected directories. This can help prevent unauthorized access attempts from specific IP addresses or ranges.

User Education

Educate users about the importance of password security, the risks of sharing passwords, and the significance of keeping their login credentials confidential. Promote good password hygiene and encourage users to report any suspicious activities or security concerns.


Password protecting web directories in Nginx is a valuable security measure to restrict access to sensitive content or areas of your website. By following the steps outlined in this guide, you can effectively implement password protection and enhance the security of your Nginx server.

Updated on: 09-Aug-2023


Kickstart Your Career

Get certified by completing the course

Get Started