nginx and auth_basic

Securing Nginx with Basic Authentication (auth_basic)

Learn how to implement basic authentication using Nginx's auth_basic module and .htpasswd files to protect web resources.

Basic authentication is a simple yet effective way to restrict access to certain parts of your website or application. Nginx, a popular web server, provides the auth_basic module to easily integrate this security measure. This article will guide you through the process of setting up basic authentication using Nginx and the htpasswd utility to create user credentials.

Understanding Nginx Basic Authentication

Nginx's auth_basic module works by prompting users for a username and password when they try to access a protected resource. These credentials are then checked against an encrypted password file, typically generated using the htpasswd utility. If the credentials match, access is granted; otherwise, the user is denied. This method is suitable for protecting administrative interfaces, staging environments, or specific directories that require restricted access.

sequenceDiagram
    actor User
    participant Browser
    participant Nginx
    participant htpasswd_file as ".htpasswd" File

    User->>Browser: Request protected resource
    Browser->>Nginx: GET /protected_resource
    Nginx->>Browser: 401 Unauthorized (WWW-Authenticate: Basic realm="Restricted Area")
    Browser->>User: Prompt for Username/Password
    User->>Browser: Enter Credentials
    Browser->>Nginx: GET /protected_resource (Authorization: Basic <base64_encoded_credentials>)
    Nginx->>htpasswd_file: Verify Credentials
    alt Credentials Valid
        htpasswd_file-->>Nginx: Valid
        Nginx->>Browser: 200 OK (Serve resource)
        Browser->>User: Display resource
    else Credentials Invalid
        htpasswd_file-->>Nginx: Invalid
        Nginx->>Browser: 401 Unauthorized (WWW-Authenticate: Basic realm="Restricted Area")
        Browser->>User: Prompt for Username/Password (again)
    end

Sequence diagram of Nginx Basic Authentication flow

Step-by-Step Implementation

Implementing basic authentication with Nginx involves two main steps: creating the password file and configuring Nginx to use it. We'll use the htpasswd utility, which is usually part of the apache2-utils or httpd-tools package, depending on your Linux distribution.

1. Install htpasswd utility

First, ensure you have the htpasswd utility installed on your server. For Debian/Ubuntu-based systems, use:

sudo apt update
sudo apt install apache2-utils

For CentOS/RHEL-based systems:

sudo yum install httpd-tools

2. Create the password file

Choose a secure location for your .htpasswd file, outside of your web root. For example, /etc/nginx/.htpasswd. To create the file and add your first user (e.g., admin), use the following command. The -c flag creates the file, and you'll be prompted to enter and confirm the password.

sudo htpasswd -c /etc/nginx/.htpasswd admin

To add additional users to an existing file, omit the -c flag:

sudo htpasswd /etc/nginx/.htpasswd newuser

Note: The -c flag will overwrite an existing file, so use it only for the first user.

3. Configure Nginx

Now, open your Nginx configuration file (e.g., /etc/nginx/sites-available/default or a specific server block file) and add the auth_basic and auth_basic_user_file directives within the location block you wish to protect.

For example, to protect the entire /admin directory:

location /admin {
    auth_basic "Restricted Area";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

To protect a specific file, like admin.html:

location = /admin.html {
    auth_basic "Restricted File";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

If you want to protect the entire site, you can place these directives within the server block:

server {
    listen 80;
    server_name example.com;

    auth_basic "Restricted Site";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        # ... your site content ...
    }
}

4. Test Nginx configuration and reload

After modifying the Nginx configuration, always test for syntax errors and then reload Nginx to apply the changes.

sudo nginx -t
sudo systemctl reload nginx

If there are no errors, Nginx will reload, and your protected resources will now require authentication.

server {
    listen 80;
    server_name your_domain.com;

    root /var/www/html;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ =404;
    }

    location /protected_area {
        auth_basic "Restricted Content";
        auth_basic_user_file /etc/nginx/.htpasswd;
        # Other directives for the protected area, e.g., proxy_pass
    }

    # Optional: Deny access to .htpasswd file if it's in web root (though it shouldn't be)
    location ~ /\.htpasswd {
        deny all;
    }
}