> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Basic Authentication

> How to set up and use HTTP Basic Authentication with NGINX using .htpasswd, configuring auth_basic and securing access for internal or limited-audience paths.

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.](https://mintcdn.com/kodekloud-c4ac6d9a/x1wBthvq78ZWHRHX/images/Nginx-for-Beginners/Security/Basic-Authentication/password-protected-browser-shield-padlock-plant.jpg?fit=max\&auto=format\&n=x1wBthvq78ZWHRHX\&q=85\&s=c1f27c877cfc4a8b293660a50435c84a)

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)

![A slide titled "Use Cases" showing two side-by-side web sign-in mockups with gradient URL bars (https://www.kodekloud.com/feature-xyz and /premium). Each mockup includes an avatar placeholder, name and password fields, a checkbox, a green "SIGN IN" button and a small padlock icon.](https://mintcdn.com/kodekloud-c4ac6d9a/x1wBthvq78ZWHRHX/images/Nginx-for-Beginners/Security/Basic-Authentication/use-cases-web-signin-mockups.jpg?fit=max\&auto=format\&n=x1wBthvq78ZWHRHX\&q=85\&s=f34eb06affda848f14bf2612c52ceed2)

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)

1. Create a password file (commonly named `.htpasswd`) containing `username:hashed-password` entries.
2. Configure an NGINX `location` or `server` block with `auth_basic` and `auth_basic_user_file` pointing to that file.
3. 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):

```bash theme={null}
sudo apt update
sudo apt install -y apache2-utils
```

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

```bash theme={null}
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):

```bash theme={null}
sudo htpasswd /etc/nginx/conf.d/.htpasswd jsmith
```

Example console output:

```text theme={null}
$ 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):

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
cat /etc/nginx/conf.d/.htpasswd
```

Sample output:

```text theme={null}
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:

```nginx theme={null}
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:

```bash theme={null}
sudo nginx -t
sudo systemctl reload nginx
```

Or, if you manage NGINX directly:

```bash theme={null}
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."](https://mintcdn.com/kodekloud-c4ac6d9a/x1wBthvq78ZWHRHX/images/Nginx-for-Beginners/Security/Basic-Authentication/testing-endpoint-authentication-required-admin-login.jpg?fit=max\&auto=format\&n=x1wBthvq78ZWHRHX\&q=85\&s=37e3733178a9f0a518ec17a27ddf00e7)

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

* [NGINX auth\_basic documentation](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html)
* [htpasswd (Apache) documentation](https://httpd.apache.org/docs/current/programs/htpasswd.html)
* [OpenSSL](https://www.openssl.org)
* [OAuth](https://oauth.net/)
* [Single sign-on (SSO) overview](https://en.wikipedia.org/wiki/Single_sign-on)

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.

> **[Watch Video](https://learn.kodekloud.com/user/courses/nginx-for-beginners/module/8905470e-b1ea-48ec-b0cd-711687ce7159/lesson/3082fc69-784b-4bf2-b7d0-b19c7fb94952)**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.