--- What is Nginx HTTP Basic Auth?

HTTP Basic Auth allowing us to restrict access in our website or just some parts of it. I would not rewrite its definition, but you may read more about it here: https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/.

--- Example by Experience

We had a development/staging environment and mock an SMTP using Mailpit. Mailpit access by default is open, it doesn’t require any authentication and it’s accessible from anywhere and by everyone. To secure Mailpit, we may do several obscuring:

• Port Obscuring: we may obscure the port, instead of exposing 8025, we change it other such as 7085 or just restrict it completely from public with a firewall (e.g. ufw).

• Domain Obscuring: we serve it under obscured domain such as mailpit.masdit.dev to mailpit-50104c1f.masdit.dev.

But that’s not enough, and here’s where the Nginx HTTP Basic Auth is useful.

--- Explanation

HTTP Basic Authentication restrict the access even if the obscured port or domain is found. Basic Authentication is a combination of username and password, so it add new layer of restriction to our exposed website. It works by adding Authorization: Bearer {basic} header on every HTTP request after authenticated.

It has two layers of restriction:

1. Restriction by username and password (basic authorization)
2. Restriction by IP addresses

The restriction can be applied in two scenarios:

[1] A user must be both authenticated AND have a valid IP address

[2] A user must be either authenticated OR have a valid IP address

--- How to configure

You can either install apache2-utils or httpd-tools—here, I use apache2-utils in Ubuntu, so I can install it by sudo apt install apache2-utils. After installation, we can run htpasswd command to generate username and password, here’s the steps:

Please note:

[a] if you run it first time, you need to use -c argument to create the .htpasswd file. Revoke -c if the .htpasswd file already exists.

[b] you can create the .htpasswd in different path.

Steps:

[1] Run sudo htpasswd -c /etc/apache2/.htpasswd user1 (if .htpasswd not exists)

[2] Run sudo htpasswd /etc/apache2/.htpasswd user2 (if .htpasswd already exists)

[3] Run cat /etc/apache2/.htpasswd to verify if the username password created successfully

[4] Configure the nginx config of your site

Here’s how it looks:

location / {
    auth_basic           "Restricted Area"; # this is up to you to modify
    auth_basic_user_file /etc/apache2/.htpasswd; # this is the path of `.htpasswd` file
}

For example of restriction using IP address, you may want to read the official Nginx documentation.

The full example is looks like this:

server {
    listen 80;
    server_name mailpit-50104c1f.masdit.dev;

    location / {
        auth_basic           "Restricted Area"; # this is up to you to modify
        auth_basic_user_file /etc/apache2/.htpasswd; # this is the path of `.htpasswd` file

        # ... proxy settings

        proxy_pass http://127.0.0.1:8025; # served from Docker
    }
}

--- Summary

Nginx HTTP Basic Auth is useful to restrict our websites. Another example is to restrict access of Opensearch and Meilisearch dashboards which is not restricted by default. Other useful example is restricting our a static file/generated Dashboard (generated by AI Agents), allowing it be restricted by default by not exposing it publicly but to anyone with access of username and password, for example is our teammate.