Basic Authentication

HTTP Basic Authentication is a simple authentication mechanism where:

1. Client requests a protected resource
2. Server responds with 401 Unauthorized
3. Browser prompts for username & password
4. Credentials are sent in the Authorization header (Base64-encoded)
5. NGINX validates credentials and allows or denies access

Base64 encoding is not encryption — credentials must be protected with HTTPS.

Why Use Basic Auth in NGINX?

Basic Auth is best suited for:

• Admin panels

• Internal dashboards

• Staging environments

• Quick protection for private endpoints

• Temporary security layers

• Easy to set up

• Handled at NGINX (no app changes)

• Not suitable for large public user bases

How Basic Auth Works Internally

HTTP Flow

Client → GET /admin
Server → 401 + WWW-Authenticate
Client → Authorization: Basic dXNlcjpwYXNz
Server → Validate → 200 OK

• Credentials are sent with every request
• Browser usually caches them for the session

Core Directives for Basic Authentication

auth_basic

auth_basic "Restricted Area";

• Enables Basic Auth
• The string is shown in the browser prompt

auth_basic_user_file

auth_basic_user_file /etc/nginx/.htpasswd;

• Path to credential file
• Format: username:hashed_password

Creating the Password File (.htpasswd)

Install tools

sudo apt install apache2-utils # Debian/Ubuntu
sudo yum install httpd-tools # RHEL/CentOS

Create user

htpasswd -c /etc/nginx/.htpasswd admin

• -c → create file (use once)
• You’ll be prompted for a password

Add more users

htpasswd /etc/nginx/.htpasswd devuser

Basic Authentication Example (Location-Level)

server {
    listen 443 ssl;
    server_name example.com;

        ssl_certificate     /path/fullchain.pem;
        ssl_certificate_key /path/privkey.pem;

        location /admin/ {
            auth_basic "Admin Area";
            auth_basic_user_file /etc/nginx/.htpasswd;

            root /var/www/admin;
            index index.html;
        }

    }

Directive	Purpose
auth_basic	Enables authentication
auth_basic_user_file	Credential store
location /admin/	Protects only admin area

• Public site stays open
• Admin area secured

Server-Wide Basic Authentication

   server {
   listen 443 ssl;
   auth_basic "Private Site";
   auth_basic_user_file /etc/nginx/.htpasswd;
   }

All paths are protected unless overridden.

Disable Auth for Specific Paths

   location /health {
   auth_basic off;
   }

Useful for load balancer health checks

Combining Basic Auth with IP Restrictions (Best Practice)

    location /admin/ {
    allow 192.168.1.0/24;
    deny all;

        auth_basic "Admin Area";
        auth_basic_user_file /etc/nginx/.htpasswd;

    }

• Defense in depth
• Reduces brute-force exposure

Protecting APIs with Basic Auth

    location /api/ {
    auth_basic "API Access";
    auth_basic_user_file /etc/nginx/api_users;
    }

Clients must send:

Authorization: Basic base64(user:password)

Security Considerations & Risks

Major Risks

Risk	Mitigation
Credentials visible over HTTP	Always use HTTPS
Brute-force attacks	Rate limit /admin
Shared credentials	Use per-user accounts
No logout mechanism	Use short sessions

Recommended Security Enhancements

Add Rate Limiting

location /admin/ {
    limit_req zone=login burst=3 nodelay;
}

Log Authentication Failures

error_log /var/log/nginx/auth_error.log warn;

Basic Auth vs Other Auth Methods

Risk	Mitigation
Credentials visible over HTTP	Always use HTTPS
Brute-force attacks	Rate limit /admin
Shared credentials	Use per-user accounts
No logout mechanism	Use short sessions

Common Mistakes

Mistake	Impact
Using Basic Auth without HTTPS	Credential theft
World-readable .htpasswd	Security breach
Reusing passwords	Account compromise
No rate limiting	Brute-force

Best-Practice Production Setup

location /admin/ {
    allow 192.168.1.0/24;
    deny all;

    auth_basic "Admin Area";
    auth_basic_user_file /etc/nginx/.htpasswd;

    limit_req zone=admin burst=2 nodelay;
}