Basic authentication in Nginx - Deep Dive

Overview - Basic authentication

What is it?

Basic authentication is a simple way to protect web pages by asking users to enter a username and password. When a user tries to access a protected page, the browser shows a login box. The username and password are sent to the server encoded but not encrypted. Nginx can be configured to use basic authentication to control access to parts of a website.

Why it matters

Without basic authentication, anyone can access sensitive or private parts of a website, which can lead to data leaks or unauthorized changes. Basic authentication provides a quick and easy way to add a layer of security, especially for internal tools or simple sites. It helps prevent unauthorized users from seeing or changing protected content.

Where it fits

Before learning basic authentication, you should understand how web servers like nginx serve content and how HTTP requests work. After mastering basic authentication, you can explore more advanced security methods like token-based authentication, SSL/TLS encryption, and OAuth.

Mental Model

Core Idea

Basic authentication is like a locked door that asks for a simple key (username and password) before letting you in.

Think of it like...

Imagine a small office with a receptionist who asks for your name and password before letting you enter. The receptionist doesn’t check your ID deeply but just verifies the password matches the list. This is like basic authentication in nginx.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ User requests │──────▶│ nginx server  │──────▶│ Checks user   │
│ a protected   │       │ with basic    │       │ credentials   │
│ page          │       │ authentication│       │ against file  │
└───────────────┘       └───────────────┘       └───────────────┘
                                   │
                                   ▼
                         ┌───────────────────┐
                         │ Access granted or  │
                         │ denied based on    │
                         │ credentials       │
                         └───────────────────┘

Build-Up - 7 Steps

1

Foundation

What is Basic Authentication

Concept: Introduce the idea of basic authentication as a simple username and password check.

Basic authentication is a method where a web server asks the user for a username and password before allowing access. The browser shows a popup login box when accessing protected content. The credentials are sent encoded in the HTTP header but not encrypted.

Result

Users see a login prompt when trying to access protected pages.

Understanding the simplest form of access control helps grasp how web servers protect resources.

2

Foundation

How nginx Uses Basic Authentication

Concept: Explain how nginx can be configured to require basic authentication for certain URLs.

Nginx uses a special configuration directive called 'auth_basic' to enable basic authentication. It also uses 'auth_basic_user_file' to point to a file containing usernames and passwords. When a user requests a protected page, nginx checks the credentials against this file.

Result

Nginx blocks access to protected pages unless valid credentials are provided.

Knowing nginx’s role in enforcing authentication clarifies how web servers control access.

3

Intermediate

Creating the Password File

🤔Before reading on: do you think the password file stores plain text passwords or encrypted ones? Commit to your answer.

Concept: Learn how to create the password file with encrypted passwords using a tool.

Use the 'htpasswd' tool to create a file with usernames and encrypted passwords. For example, run 'htpasswd -c /etc/nginx/.htpasswd user1' to create the file and add a user. The passwords are stored encrypted, not in plain text.

Result

A file '/etc/nginx/.htpasswd' is created with encrypted user credentials.

Knowing that passwords are encrypted in the file improves security and prevents easy leaks.

4

Intermediate

Configuring nginx for Basic Authentication

🤔Before reading on: do you think you need to reload nginx after changing the config? Commit to your answer.

Concept: Learn the exact nginx configuration syntax to enable basic authentication on a location.

In the nginx config file, inside a server block, add: location /protected/ { auth_basic "Restricted Area"; auth_basic_user_file /etc/nginx/.htpasswd; } Then reload nginx with 'nginx -s reload' to apply changes.

Result

Accessing '/protected/' URL prompts for username and password.

Understanding configuration syntax and reload process is key to applying changes effectively.

5

Intermediate

How Browsers Handle Basic Authentication

Concept: Explain how browsers send credentials and cache them during a session.

When the browser receives a 401 Unauthorized response with a 'WWW-Authenticate' header, it shows a login popup. After entering credentials, it sends them in the 'Authorization' header on every request to the protected area. Browsers cache these credentials until the tab or browser is closed.

Result

Users only enter credentials once per session unless they close the browser.

Knowing browser behavior helps predict user experience and troubleshoot login issues.

6

Advanced

Security Limitations of Basic Authentication

🤔Before reading on: do you think basic authentication encrypts passwords during transmission? Commit to your answer.

Concept: Understand why basic authentication alone is not secure over plain HTTP.

Basic authentication sends credentials encoded in base64, which is easy to decode. Without HTTPS, anyone intercepting the traffic can see usernames and passwords. Therefore, basic authentication should always be used with HTTPS to encrypt the connection.

Result

Basic authentication is secure only when combined with HTTPS.

Recognizing the need for HTTPS prevents serious security risks in production.

7

Expert

Advanced nginx Authentication Techniques

🤔Before reading on: do you think nginx can combine basic authentication with other methods like IP whitelisting? Commit to your answer.

Concept: Explore how nginx can combine basic authentication with other access controls and how to handle multiple authentication files.

Nginx allows combining basic authentication with IP-based access control using 'allow' and 'deny' directives. You can also use multiple 'location' blocks with different 'auth_basic_user_file' files for different areas. Additionally, nginx supports modules for more advanced authentication like JWT or OAuth.

Result

Nginx can enforce layered and flexible access control strategies.

Knowing how to combine methods enables building secure and flexible production systems.

Under the Hood

When a user requests a protected resource, nginx checks the HTTP 'Authorization' header for credentials. If missing or invalid, nginx responds with '401 Unauthorized' and a 'WWW-Authenticate' header prompting the browser to ask the user for credentials. The browser encodes the username and password in base64 and sends it back in the 'Authorization' header. Nginx compares this encoded string against entries in the password file, which stores usernames and encrypted passwords. If they match, access is granted; otherwise, denied.

Why designed this way?

Basic authentication was designed as a simple, stateless way to protect resources without complex session management. It uses standard HTTP headers to communicate credentials, making it easy to implement in clients and servers. The use of base64 encoding was chosen for simplicity, not security, assuming it would be combined with encryption like HTTPS. Alternatives like digest authentication were more complex and less widely supported.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Client sends  │──────▶│ nginx checks  │──────▶│ Password file │
│ request with  │       │ Authorization │       │ with encrypted│
│ Authorization │       │ header        │       │ passwords     │
│ header        │       └───────────────┘       └───────────────┘
└───────────────┘               │
                                ▼
                      ┌───────────────────┐
                      │ If valid, serve   │
                      │ content; else     │
                      │ respond 401 with  │
                      │ WWW-Authenticate  │
                      └───────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does basic authentication encrypt passwords during transmission? Commit to yes or no.

Common Belief: Basic authentication encrypts the password when sending it over the network.

Reality: Basic authentication only encodes the password in base64, which is not encryption and can be easily decoded.

Why it matters: Assuming encryption leads to using basic authentication over plain HTTP, exposing credentials to attackers.

Quick: Can you protect your site by just adding basic authentication without HTTPS? Commit to yes or no.

Common Belief: Basic authentication alone is enough to secure a website.

Reality: Without HTTPS, basic authentication credentials can be intercepted and stolen.

Why it matters: This misconception causes serious security breaches in production environments.

Quick: Does nginx store passwords in plain text in the password file? Commit to yes or no.

Common Belief: Nginx stores user passwords in plain text in the password file.

Reality: Passwords in the password file are encrypted (hashed), not stored in plain text.

Why it matters: Knowing this helps admins trust the security of the password file and manage it properly.

Quick: Can you use multiple password files for different site sections in nginx? Commit to yes or no.

Common Belief: You can only use one password file for the entire nginx server.

Reality: Nginx allows different password files for different locations or server blocks.

Why it matters: This flexibility enables better access control and user management.

Expert Zone

1

Nginx processes authentication before serving content, so misconfigurations can block legitimate users silently.

2

The 'auth_basic' directive’s message string appears in the browser’s login popup, which can be customized for better user experience.

3

Password files can be managed externally and updated without restarting nginx by using 'nginx -s reload', allowing zero downtime.

When NOT to use

Basic authentication is not suitable for public-facing sites requiring strong security or user sessions. Instead, use token-based authentication like OAuth or JWT combined with HTTPS. For APIs, prefer OAuth or API keys. For complex user management, use dedicated identity providers.

Production Patterns

In production, basic authentication is often used to protect staging or admin areas behind HTTPS. It is combined with IP whitelisting for extra security. Password files are managed with automation tools, and logs are monitored for unauthorized access attempts.

Connections

HTTPS (TLS Encryption)

Builds-on

Basic authentication relies on HTTPS to encrypt credentials during transmission, making the combination essential for secure access control.

HTTP Headers

Same pattern

Basic authentication uses standard HTTP headers ('Authorization' and 'WWW-Authenticate') to communicate credentials, showing how headers control client-server interactions.

Physical Security Locks

Analogy in security

Just like a physical lock controls access to a room, basic authentication controls access to web resources, highlighting universal principles of access control.

Common Pitfalls

#1 Using basic authentication without HTTPS.

Wrong approach:

location /secure/ {
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;
}
# Site served over HTTP only

Correct approach:

server {
listen 443 ssl;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location /secure/ {
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;
}
}

Root cause:

Misunderstanding that basic authentication encrypts credentials, ignoring the need for HTTPS.

#2 Storing passwords in plain text in the password file.

Wrong approach:

user1:password123
user2:password456

Correct approach:

user1:$apr1$randomsalt$encryptedhash
user2:$apr1$randomsalt$encryptedhash

Root cause:

Not using the 'htpasswd' tool or similar to encrypt passwords before storing.

#3 Forgetting to reload nginx after changing config.

Wrong approach:

Edit nginx.conf to add auth_basic but do not reload nginx.

Correct approach:

After editing nginx.conf, run 'nginx -s reload' to apply changes.

Root cause:

Not knowing nginx requires reload to apply configuration changes.

Key Takeaways

Basic authentication is a simple username and password check that protects web resources by asking users to log in.

Nginx uses 'auth_basic' and 'auth_basic_user_file' directives to enable and configure basic authentication.

Passwords in the authentication file are encrypted, not stored in plain text, improving security.

Basic authentication alone is not secure over plain HTTP; it must be combined with HTTPS to protect credentials.

Advanced nginx setups combine basic authentication with other access controls for flexible and secure production environments.

Practice

1. What is the main purpose of basic authentication in nginx?

easy

A. To speed up the website loading time

B. To encrypt all website traffic automatically

C. To require users to enter a username and password before accessing content

D. To block all users except the server admin

Solution

1. Step 1: Understand basic authentication purpose

   Basic authentication prompts users for a username and password to restrict access.

2. Step 2: Compare options

   Only To require users to enter a username and password before accessing content describes this login prompt function; others describe unrelated features.

3. Final Answer:

   To require users to enter a username and password before accessing content -> Option C

4. Quick Check:

   Basic authentication = login prompt [OK]

Hint: Basic auth means login prompt for access control [OK]

Common Mistakes:

• Confusing basic auth with encryption
• Thinking it speeds up the site
• Assuming it blocks all users except admin

2. Which nginx directive is used to enable basic authentication in a server block?

easy

A. auth_basic_user_file

B. auth_user_file

C. basic_auth_enable

D. auth_basic

Solution

1. Step 1: Identify the directive for enabling basic auth

   The directive auth_basic enables basic authentication and sets the login prompt message.

2. Step 2: Check other directives

   auth_basic_user_file is incorrect; the correct directive for the password file is auth_basic_user_file but the enabling directive is auth_basic.

3. Final Answer:

   auth_basic -> Option D

4. Quick Check:

   Enable basic auth = auth_basic [OK]

Hint: Enable basic auth with auth_basic directive [OK]

Common Mistakes:

• Using auth_basic_user_file to enable auth
• Confusing directive names
• Using non-existent directives

3. Given this nginx config snippet:

location /secure/ {
  auth_basic "Restricted Area";
  auth_basic_user_file /etc/nginx/.htpasswd;
}

What happens when a user tries to access /secure/?

medium

A. User is prompted for username and password

B. User is redirected to /etc/nginx/.htpasswd

C. User accesses content without any prompt

D. User gets a 404 Not Found error

Solution

1. Step 1: Analyze auth_basic directive

   The auth_basic directive enables a login prompt with the message "Restricted Area".

2. Step 2: Analyze auth_basic_user_file directive

   The auth_basic_user_file points to the password file used to verify credentials.

3. Step 3: Determine user experience

   When accessing /secure/, the user is asked for username and password to proceed.

4. Final Answer:

   User is prompted for username and password -> Option A

5. Quick Check:

   auth_basic + user_file = login prompt [OK]

Hint: auth_basic triggers login prompt on matching location [OK]

Common Mistakes:

• Thinking user is redirected to password file
• Assuming no prompt appears
• Expecting 404 error without reason

4. You configured basic authentication but users are not prompted for credentials. Which is the most likely error?

medium

A. Missing auth_basic directive in the location block

B. Password file has wrong permissions

C. Using HTTP instead of HTTPS

D. Incorrect server_name directive

Solution

1. Step 1: Check required directives for basic auth

   Both auth_basic and auth_basic_user_file are needed; missing auth_basic disables the prompt.

2. Step 2: Evaluate other options

   Wrong permissions cause errors but usually show 500 errors; HTTP vs HTTPS affects security but not prompt; server_name unrelated.

3. Final Answer:

   Missing auth_basic directive in the location block -> Option A

4. Quick Check:

   No auth_basic = no login prompt [OK]

Hint: Always include auth_basic to enable prompt [OK]

Common Mistakes:

• Ignoring missing auth_basic directive
• Blaming HTTPS for prompt absence
• Confusing server_name with auth settings

5. You want to protect only the /admin path with basic authentication but allow /admin/public without login. Which nginx config achieves this?

hard

A. Use location /admin/public/ { auth_basic "Admin Area"; } and location /admin/ { auth_basic off; }

B. Use location /admin/ { auth_basic "Admin Area"; auth_basic_user_file /etc/nginx/.htpasswd; } and location /admin/public/ { auth_basic off; }

C. Use location /admin/ { auth_basic off; } only

D. Use location /admin/public/ { auth_basic_user_file /etc/nginx/.htpasswd; } only

Solution

1. Step 1: Protect /admin path with basic auth

   Set auth_basic and auth_basic_user_file in location /admin/ to require login.

2. Step 2: Disable auth for /admin/public

   Override with auth_basic off; in location /admin/public/ to allow open access.

3. Step 3: Confirm correct order and specificity

   More specific location /admin/public/ disables auth, while parent /admin/ requires it.

4. Final Answer:

   Use location /admin/ with auth_basic and location /admin/public/ with auth_basic off -> Option B

5. Quick Check:

   Parent location auth + child location off = selective protection [OK]

Hint: Disable auth in child location with auth_basic off [OK]

Common Mistakes:

• Reversing auth_basic on/off in locations
• Not using auth_basic off to disable
• Only configuring one location