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.

Steps to enable basic authentication in Nginx:

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.
Install the password-file utility on Debian or Ubuntu.
```
$ sudo apt install --assume-yes apache2-utils
```
On RHEL-family systems, install httpd-tools.
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.
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.
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.
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
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
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
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
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.