0
0
Nginxdevops~5 mins

Basic authentication in Nginx - Commands & Configuration

Choose your learning style9 modes available
LearnWhyDeepVisualTryChallengeProjectRecallTime
Introduction
Sometimes you want to protect a website or a part of it so only certain people can see it. Basic authentication is a simple way to ask users for a username and password before they can access the page.
When you want to protect a small admin page on your website without setting up a full login system
When you need a quick password check for a staging or testing site before sharing it
When you want to restrict access to certain files or folders on your web server
When you want to add a simple layer of security to your website without complex coding
When you want to control access to a private API endpoint
Config File - nginx.conf
nginx.conf
server {
    listen 80;
    server_name example.com;

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

This configuration tells Nginx to listen on port 80 for the domain example.com.

The location /secure/ block protects the /secure/ path.

auth_basic sets the message shown in the login popup.

auth_basic_user_file points to the file with usernames and passwords.

Commands
Install the tool 'htpasswd' which helps create the password file for basic authentication.
Terminal
sudo apt-get update && sudo apt-get install apache2-utils -y
Expected OutputExpected
Reading package lists... Done Building dependency tree Reading state information... Done The following NEW packages will be installed: apache2-utils 0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded. Need to get 123 kB of archives. After this operation, 456 kB of additional disk space will be used. Get:1 http://archive.ubuntu.com/ubuntu focal/main amd64 apache2-utils amd64 2.4.41-4ubuntu3.9 [123 kB] Fetched 123 kB in 1s (123 kB/s) Selecting previously unselected package apache2-utils. (Reading database ... 123456 files and directories currently installed.) Preparing to unpack .../apache2-utils_2.4.41-4ubuntu3.9_amd64.deb ... Unpacking apache2-utils (2.4.41-4ubuntu3.9) ... Setting up apache2-utils (2.4.41-4ubuntu3.9) ...
Create a new password file and add a user named 'user1'. You will be asked to enter and confirm the password.
Terminal
sudo htpasswd -c /etc/nginx/.htpasswd user1
Expected OutputExpected
New password: Re-type new password: Adding password for user user1
→
-c - Create a new password file, overwriting if it exists
Check if the Nginx configuration file is valid before restarting the server.
Terminal
sudo nginx -t
Expected OutputExpected
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful
Reload Nginx to apply the new configuration without stopping the server.
Terminal
sudo systemctl reload nginx
Expected OutputExpected
No output (command runs silently)
Test accessing the protected URL. It should ask for authentication and respond with 401 Unauthorized if no credentials are provided.
Terminal
curl -i http://example.com/secure/
Expected OutputExpected
HTTP/1.1 401 Unauthorized Server: nginx/1.18.0 Date: Thu, 01 Jan 1970 00:00:00 GMT Content-Type: text/html Content-Length: 178 WWW-Authenticate: Basic realm="Restricted Content" <html> <head><title>401 Authorization Required</title></head> <body bgcolor="white"> <center><h1>401 Authorization Required</h1></center> <hr><center>nginx/1.18.0</center> </body> </html>
Key Concept

If you remember nothing else from this pattern, remember: basic authentication protects web content by asking users for a username and password stored in a simple file.

Common Mistakes
Not creating the password file before enabling basic authentication in Nginx
Nginx will fail to start or the protected area will not work because it cannot find the user file.
Always create the .htpasswd file with at least one user before reloading Nginx.
Using the -c flag with htpasswd to add users after the file already exists
The -c flag overwrites the existing file, deleting all previous users.
Use htpasswd without -c to add additional users to the existing file.
Not testing Nginx configuration with 'nginx -t' before reloading
If there is a syntax error, Nginx reload will fail and the server may stop serving requests.
Always run 'sudo nginx -t' to check configuration syntax before reloading.
Summary
Install 'apache2-utils' to get the htpasswd tool for creating password files.
Create a .htpasswd file with usernames and passwords using 'htpasswd -c' for the first user.
Configure Nginx to protect a location with 'auth_basic' and point to the .htpasswd file.
Test the Nginx configuration with 'nginx -t' and reload Nginx to apply changes.
Verify protection by accessing the protected URL and checking for authentication prompt.