Basic authentication in Nginx - Step-by-Step Execution

Process Flow - Basic authentication

Client sends HTTP request

↓

Nginx checks for Authorization header

↓

Decode credentials

↓

Verify username/password

↓

Allow

Nginx checks if the client sent credentials. If missing or wrong, it asks again. If correct, it allows access.

Execution Sample

Nginx

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

This config protects /secure path with basic auth using credentials in .htpasswd file.

Process Table

Step	Client Request	Authorization Header	Action	Nginx Response
1	GET /secure	None	Check header	401 Unauthorized with WWW-Authenticate
2	GET /secure	Basic dXNlcjpwYXNz	Decode and verify	Credentials valid?
3	GET /secure	Basic dXNlcjpwYXNz	Credentials valid	200 OK, allow access
4	GET /secure	Basic d3Jvbmc6Y3JlZA==	Credentials invalid	401 Unauthorized with WWW-Authenticate

💡 Execution stops when client sends valid credentials or after 401 response for invalid/missing credentials.

Status Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4
Authorization Header	None	None	Basic dXNlcjpwYXNz	Basic dXNlcjpwYXNz	Basic d3Jvbmc6Y3JlZA==
Credentials Valid	N/A	N/A	True	True	False
Response Code	N/A	401	Checking	200	401

Key Moments - 3 Insights

Why does nginx respond with 401 Unauthorized when no Authorization header is sent?

Because nginx requires credentials for the protected path. Without the header, it sends 401 to ask the client to provide them (see execution_table step 1).

What happens if the credentials are invalid?

Nginx responds again with 401 Unauthorized, prompting the client to retry (see execution_table step 4).

How does nginx know if credentials are valid?

It decodes the Authorization header and checks against the .htpasswd file (see execution_table step 2 and variable_tracker Credentials Valid).

Visual Quiz - 3 Questions

Look at the execution_table, what response does nginx send when the Authorization header is missing?

A 403 Forbidden

B 200 OK

C 401 Unauthorized with WWW-Authenticate

D 500 Internal Server Error

💡 Hint

Check execution_table row 1 under Nginx Response

At which step does nginx allow access to the client?

A Step 3

B Step 2

C Step 1

D Step 4

💡 Hint

Look for 200 OK response in execution_table

If the Authorization header changes to an invalid value, what response code will nginx send?

A 200 OK

B 401 Unauthorized

C 404 Not Found

D 302 Redirect

💡 Hint

See execution_table step 4 Response Code and variable_tracker Response Code after step 4

Concept Snapshot

Basic authentication in nginx:
- Use auth_basic and auth_basic_user_file in location block
- Client sends Authorization header with base64 user:pass
- Nginx checks header; if missing or invalid, sends 401 Unauthorized
- If valid, nginx allows access
- Credentials stored in .htpasswd file

Full Transcript

Basic authentication in nginx works by requiring clients to send a special header with username and password encoded. When a client requests a protected path, nginx looks for the Authorization header. If it is missing, nginx responds with 401 Unauthorized and a prompt to send credentials. When the client sends credentials, nginx decodes and checks them against a password file. If valid, nginx allows access with a 200 OK response. If invalid, nginx again responds with 401 Unauthorized. This process repeats until valid credentials are provided or the client stops trying.