How to enable basic authentication in Nginx

Staging sites, internal dashboards, and administrative endpoints often need a quick access gate that blocks casual browsing and automated scans without changing the application. Basic authentication in Nginx adds that gate at the web server layer by requiring a username and password before content is served from a protected path.

HTTP Basic authentication works by sending a challenge (401 Unauthorized) and a realm via the WWW-Authenticate header, after which the client retries with an Authorization header. Nginx validates the supplied credentials against a password file (commonly created with htpasswd) referenced by auth_basic_user_file.

Basic authentication should be used with HTTPS because credentials are only base64-encoded, not encrypted. Keep the password file outside the web root, restrict permissions so only Nginx can read it, and avoid using Basic auth as the only control for highly sensitive public-facing resources.

1. Install the htpasswd utility on Ubuntu or Debian.

   $ sudo apt update && sudo apt install --assume-yes apache2-utils
   ##### snipped #####
   Setting up apache2-utils ...
   Processing triggers for man-db ...

   On RHEL-family systems, install httpd-tools (for example: sudo dnf install --assumeyes httpd-tools).

2. Create the password file at /etc/nginx/.htpasswd by adding the first user.

   $ sudo htpasswd -c /etc/nginx/.htpasswd admin
   New password:
   Re-type new password:
   Adding password for user admin

   The -c flag creates a new file; omit it when adding additional users to avoid overwriting existing entries.

   Add another user with sudo htpasswd /etc/nginx/.htpasswd alice.

3. Check the configured Nginx runtime user in /etc/nginx/nginx.conf.

   $ sudo grep -E '^\s*user\s' /etc/nginx/nginx.conf
   user www-data;

   If the user directive is missing or commented out, the packaged default is commonly www-data or nginx.

4. Set the password file group to the Nginx runtime user.

   $ sudo chown root:www-data /etc/nginx/.htpasswd

   Replace www-data with the configured runtime user.

5. Restrict the password file permissions to owner read/write and group read.

   $ sudo chmod 640 /etc/nginx/.htpasswd

   World-readable permissions can expose credential hashes to other local users on the host.

6. Add auth_basic directives to the protected location in the relevant server block.

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

   Common config locations include /etc/nginx/sites-available (Debian-style) and /etc/nginx/conf.d (RHEL-family).

   The realm string appears in the browser login prompt.

7. Test the Nginx configuration for syntax errors.

   $ sudo nginx -t
   nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
   nginx: configuration file /etc/nginx/nginx.conf test is successful

8. Reload Nginx to apply the configuration change.

   $ sudo systemctl reload nginx

9. Confirm the protected URL responds with 401 Unauthorized when no credentials are supplied.

   $ curl -I http://127.0.0.1/admin/
   HTTP/1.1 401 Unauthorized
   Server: nginx
   WWW-Authenticate: Basic realm="Restricted"
   ##### snipped #####

10. Confirm the protected URL responds with 200 OK when valid credentials are supplied.

    $ curl -I -u admin http://127.0.0.1/admin/
    Enter host password for user 'admin':
    HTTP/1.1 200 OK
    Server: nginx
    ##### snipped #####

    Testing against a remote host should use HTTPS; Basic authentication over plain HTTP exposes credentials in transit.