Basic Authentication

NGINX can provide HTTP Basic Authentication to protect an entire site or specific paths. While most public-facing applications should use application-level authentication (OAuth, SSO, or built-in frameworks), NGINX basic auth is a simple, reliable option for internal resources, admin panels, or pre-release feature pages.

A minimalist illustration of a password-protected webpage: a translucent browser window with an address/search bar and a shield bearing a padlock, set over a faint office background and a small potted plant.

Use case example: you want the public site (for example, https://www.kodekloud.com) publicly accessible, but require a username and password for https://www.kodekloud.com/admin. Common use cases:

Admin panels
Feature-flagged pages during development (e.g., https://www.kodekloud.com/feature-xyz)
Exclusive or premium content
Internal-only resources (VPN/intranet)

Use NGINX basic auth primarily for internal or limited-audience protection. For public-facing sites, prefer application-level authentication (OAuth, SSO, etc.) because the browser-native prompt is not user-friendly or brandable.

How it works (high level)

Create a password file (commonly named .htpasswd) containing username:hashed-password entries.
Configure an NGINX location or server block with auth_basic and auth_basic_user_file pointing to that file.
Test the configuration and reload NGINX. Browsers will show a native username/password prompt for protected paths.

Prerequisites

Root/sudo access to the server running NGINX.
NGINX installed and running.
Either the htpasswd utility (from apache2-utils) or OpenSSL available for generating password hashes.

Generating the password file (.htpasswd)

You can create .htpasswd with one of two common approaches. Option A — Using the htpasswd utility (recommended)

Install the utility (example for Ubuntu/Debian):

sudo apt update
sudo apt install -y apache2-utils

Create the .htpasswd file and add the first user (-c creates/truncates the file):

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

You will be prompted to enter and confirm the password.

Add another user (do NOT use -c again, or it will overwrite the file):

sudo htpasswd /etc/nginx/conf.d/.htpasswd jsmith

Example console output:

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

$ sudo htpasswd /etc/nginx/conf.d/.htpasswd jsmith
New password:
Re-type new password:
Adding password for user jsmith

Option B — Using OpenSSL (no extra package required) OpenSSL is commonly installed on most Linux distributions. Use it to produce the same username:hash format used by htpasswd.

Create the file and add the first user (use > to create/truncate):

sudo sh -c "echo -n 'admin:' > /etc/nginx/conf.d/.htpasswd"
sudo sh -c "openssl passwd -apr1 >> /etc/nginx/conf.d/.htpasswd"

OpenSSL will prompt you to enter and verify the password.

Append another user:

sudo sh -c "echo -n 'jsmith:' >> /etc/nginx/conf.d/.htpasswd"
sudo sh -c "openssl passwd -apr1 >> /etc/nginx/conf.d/.htpasswd"

View the resulting file:

cat /etc/nginx/conf.d/.htpasswd

Sample output:

admin:$apr1$egX1fPMK$EXwGqVFsOSBFsQNJMc2iB0
jsmith:$apr1$L5aCfsuK$XPsXg11JMTQpd0ihTVyus.

Passwords are stored as hashes (one-way). Keep password records in a secure vault (for example, 1Password or HashiCorp Vault).

Quick reference: common commands

Task	Command / Example
Install htpasswd (Ubuntu/Debian)	`sudo apt install -y apache2-utils`
Create `.htpasswd` with htpasswd	`sudo htpasswd -c /etc/nginx/conf.d/.htpasswd admin`
Add user with htpasswd	`sudo htpasswd /etc/nginx/conf.d/.htpasswd jsmith`
Create `.htpasswd` with OpenSSL	`sudo sh -c "echo -n 'admin:' > /etc/nginx/conf.d/.htpasswd"` `sudo sh -c "openssl passwd -apr1 >> /etc/nginx/conf.d/.htpasswd"`
View `.htpasswd`	`cat /etc/nginx/conf.d/.htpasswd`

Configuring NGINX to require authentication

Add auth_basic and auth_basic_user_file inside the location (or server) block for the path you want to protect. The auth_basic string is displayed in the browser prompt (for example, “Restricted Content”). Example NGINX server block:

server {
    listen 80;
    server_name example.com www.example.com;

    root /var/www/example.com/html;
    index index.html;

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

After saving the configuration, always test and reload NGINX:

sudo nginx -t
sudo systemctl reload nginx

Or, if you manage NGINX directly:

sudo nginx -s reload

Testing the protected endpoint

Visit the protected path in a browser (for example, http://example.com/admin). The browser will display the native authentication dialog asking for username and password.

A browser screenshot showing an "Authentication Required" dialog prompting for a username and password to access an https admin login. The slide is titled "Testing the Endpoint."

The browser’s authentication dialog is not customizable. For public-facing or branded login experiences, use an application-level authentication solution (OAuth, SSO, etc.). Basic auth is best suited for internal, temporary, or limited-audience protection.

Security and operational tips

Use HTTPS to protect credentials in transit. Basic auth sends credentials in a base64-encoded form; without TLS they can be intercepted.
Store .htpasswd outside web root and restrict file permissions (readable only by the NGINX user).
For more advanced access control, combine NGINX auth with IP allow/deny rules, client certificates, or application-level auth.
Rotate passwords and audit .htpasswd access as part of your security policy.
Consider centralized secret stores (e.g., HashiCorp Vault) for production-grade credential management.

References and further reading

That’s the essential workflow for enabling Basic Authentication with NGINX. Try this on a test server or lab environment to get hands-on practice with .htpasswd files and protected paths.

Introduction

Install & Config

Intermediate Config

Security

Performance

Conclusion

Basic Authentication

How it works (high level)

Prerequisites

Generating the password file (.htpasswd)

Quick reference: common commands

Configuring NGINX to require authentication

Testing the protected endpoint

Security and operational tips

References and further reading

Watch Video

​How it works (high level)

​Prerequisites

​Generating the password file (.htpasswd)

​Quick reference: common commands

​Configuring NGINX to require authentication

​Testing the protected endpoint

​Security and operational tips

​References and further reading

Watch Video

How it works (high level)

Prerequisites

Generating the password file (.htpasswd)

Quick reference: common commands

Configuring NGINX to require authentication

Testing the protected endpoint

Security and operational tips

References and further reading