How to enable basic authentication in Nginx

Use Nginx basic authentication when a staging site, internal dashboard, or administrative path must ask for credentials before the application handles the request. The browser receives a 401 Unauthorized response with a WWW-Authenticate challenge until a listed user supplies a valid password.

The auth_basic directive tells Nginx to return an HTTP Basic challenge, and auth_basic_user_file points at the password file that holds allowed usernames and password hashes. Current Nginx documentation uses the Apache htpasswd utility for that file, with apache2-utils on Debian and Ubuntu systems and httpd-tools on RHEL-family systems.

Basic authentication protects the path boundary, not the password in transit. Publish the protected URL only over HTTPS, keep the password file outside the document root, restrict its permissions so Nginx can read it without exposing hashes to other local users, and use nginx -s reload only when systemd is not managing the service.

1. Open the Nginx server block or included configuration file that serves the path to protect.

   $ sudoedit /etc/nginx/sites-available/example.com.conf

   Common edit locations include /etc/nginx/nginx.conf, /etc/nginx/conf.d/, and /etc/nginx/sites-available/ depending on distribution packaging.

2. Install the password-file utility on Debian or Ubuntu.

   $ sudo apt install --assume-yes apache2-utils

   On RHEL-family systems, install httpd-tools.

3. Create the password file outside the web root and add the first allowed user.

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

   The -c option creates a new file and truncates an existing one. Omit -c when adding another user.

   -B stores a bcrypt hash. Use htpasswd -i for automation that reads from stdin, and avoid -b unless the environment is tightly controlled because it exposes the password on the command line.

4. Confirm the Nginx worker account or group from the loaded configuration before setting password-file ownership.

   user www-data;

   Packaged defaults commonly use www-data or nginx. Check the active user directive in /etc/nginx/nginx.conf or an included main-context file.

5. Restrict the password file so root keeps ownership and the Nginx worker group can read it.

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

   Replace www-data with the active Nginx runtime group on the host.

   If the Nginx worker cannot read the password file, authenticated requests can fail after the reload. World-readable permissions expose password hashes to other local users.

6. Add the authentication directives to the location or server block that should require credentials.

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

   Place the directives at the server level to protect the whole virtual host. Use auth_basic off; inside a child location when one subpath must stay public. Combine auth_basic with allow, deny, and satisfy only when access also depends on client address.

   Related: How to restrict access by IP in Nginx

7. Test the Nginx configuration before reloading it.

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

   A clean result confirms the configuration parses. The HTTP checks below prove that the worker can read the password file and apply the challenge.

   Related: How to test Nginx configuration

8. Reload Nginx so the protected location starts challenging requests.

   $ sudo systemctl reload nginx

   Use sudo nginx -s reload on hosts where systemd is not managing the service.

   Related: How to manage the Nginx service

9. Confirm the protected URL now returns an authentication challenge when no credentials are supplied.

   $ curl -I -sS http://127.0.0.1:8080/admin/
   HTTP/1.1 401 Unauthorized
   Server: nginx/1.28.3 (Ubuntu)
   Date: Sat, 06 Jun 2026 11:33:14 GMT
   Content-Type: text/html
   Content-Length: 188
   Connection: keep-alive
   WWW-Authenticate: Basic realm="Restricted area"

   Use the real hostname, port, and protected path for the site being changed. The 401 Unauthorized status plus the WWW-Authenticate header shows that Nginx is challenging the path.

   Tool: HTTP Header Checker

10. Confirm the same URL returns the expected response when valid credentials are supplied.

    $ curl -I -sS --user admin http://127.0.0.1:8080/admin/
    Enter host password for user 'admin':
    HTTP/1.1 200 OK
    Server: nginx/1.28.3 (Ubuntu)
    Date: Sat, 06 Jun 2026 11:33:14 GMT
    Content-Type: text/html
    Content-Length: 21
    Last-Modified: Sat, 06 Jun 2026 11:33:14 GMT
    Connection: keep-alive
    ETag: "6a24057a-15"
    Accept-Ranges: bytes

    Leaving the password out of the command lets curl prompt for it instead of saving it in shell history.

    Expose the protected path through HTTPS before giving the URL to other users. The local HTTP check only proves that Nginx challenges and accepts credentials in the configured path.