Demo Authentication

In this lesson we implement basic authentication on an NGINX server to protect a single endpoint. The public site will remain open, while an /admin path will require a username and password. Example site:

https://www.example.com

Open a terminal on the NGINX host and confirm the site is reachable. The generic public page looks like this:

A screenshot of a clean webpage template called "Phantom" with a large headline announcing it's a free, fully responsive HTML5 UP template. Below the header is a grid of colorful square tiles labeled with words like "Magna", "Lorem", and "Feugiat".

At this point, visiting https://www.example.com/admin shows the same public page because authentication isn’t enabled yet. We’ll update the NGINX configuration to require Basic Auth only for the /admin location.

Update the NGINX server configuration

Edit your site configuration (for example /etc/nginx/sites-available/example-https) and add a location /admin block with auth_basic and auth_basic_user_file. This example server block shows a minimal HTTPS configuration with the /admin protection:

server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name example.com www.example.com;

    ssl_certificate /etc/ssl/certs/example.com.pem;
    ssl_certificate_key /etc/ssl/certs/example.com-key.pem;

    root /var/www/html;

    add_header Strict-Transport-Security "max-age=31560000; includeSubDomains; preload";
    add_header X-Frame-Options "SAMEORIGIN";
    add_header Content-Security-Policy "default-src 'self'";
    add_header Referrer-Policy origin;

    # Add index.php to the list if you are using PHP
    index index.html index.htm index.nginx-debian.html;

    location / {
        # First attempt to serve request as file, then
        # as directory, then fall back to displaying a 404.
        try_files $uri $uri/ =404;
    }

    location /admin {
        auth_basic "Restricted Access";
        auth_basic_user_file /etc/nginx/conf.d/.htpasswd;
    }
}

Quick reference: what the key directives do

Directive	Purpose	Example
`auth_basic`	Sets the authentication realm shown in the browser prompt	`auth_basic "Restricted Access";`
`auth_basic_user_file`	Path to the htpasswd-style file with encrypted credentials	`auth_basic_user_file /etc/nginx/conf.d/.htpasswd;`
`try_files`	Fallback behavior to serve files or return 404	`try_files $uri $uri/ =404;`
`ssl_certificate` / `ssl_certificate_key`	TLS certificate and key location	`/etc/ssl/certs/example.com.pem`

Notes:

auth_basic is the realm string that appears in the browser prompt (here: "Restricted Access").
auth_basic_user_file should point to a readable file containing username:encrypted-password entries.

Create the `.htpasswd` file and add a user

Create the .htpasswd file and add a user (we’ll add admin in this example). The commands below create or overwrite the file and append an APR1 (Apache MD5) encrypted password produced by openssl passwd:

# Create or overwrite .htpasswd with the username and trailing colon
sudo sh -c "echo -n 'admin:' > /etc/nginx/conf.d/.htpasswd"

# Append an APR1 (Apache MD5) encrypted password (you will be prompted for the password)
sudo sh -c "openssl passwd -apr1 >> /etc/nginx/conf.d/.htpasswd"

When prompted enter the desired password (demo uses password123). The .htpasswd file will contain a single line similar to:

admin:$apr1$MASb7ZA.$b8LOCauVuqug5nH2AIk72/

Verify the file content:

sudo cat /etc/nginx/conf.d/.htpasswd
# Example output:
# admin:$apr1$MASb7ZA.$b8LOCauVuqug5nH2AIk72/

Ensure the .htpasswd file is readable by the NGINX worker process (adjust ownership or permissions as needed). For example:

sudo chown root:nginx /etc/nginx/conf.d/.htpasswd
sudo chmod 640 /etc/nginx/conf.d/.htpasswd

Avoid world-writable/readable permissions on sensitive files.

Test and reload NGINX

Validate the configuration and reload NGINX so changes take effect:

sudo nginx -t
sudo nginx -s reload
# Or, on systems using systemd:
# sudo systemctl reload nginx

Now visit the protected endpoint. Refresh https://www.example.com/admin — the browser should prompt for credentials:

A browser screenshot showing a sign-in dialog box with username and password fields and "Cancel" and "Sign In" buttons near the top center. The address bar displays a kodekloud.dev URL.

Enter the username (admin) and the password you created (e.g., password123). After successful authentication you gain access to /admin. The public / endpoint remains accessible without credentials.

Protecting the entire site

If you prefer to require authentication for the entire site, move the auth_basic and auth_basic_user_file directives into the location / block or the server block (scope depends on your needs). Example replacing the earlier location /:

location / {
    auth_basic "Restricted Access";
    auth_basic_user_file /etc/nginx/conf.d/.htpasswd;
    try_files $uri $uri/ =404;
}

After editing, run nginx -t and reload NGINX. Note: browsers may cache credentials; use a private/incognito window or clear credentials if you do not see the login prompt immediately.

Basic authentication with .htpasswd is simple and useful for internal or small-scale protection, but it does not scale well for large production deployments. Credentials are sent with every request and managing many users via .htpasswd becomes cumbersome. For production consider more robust solutions like OAuth, OpenID Connect, or integrating with an identity provider or SSO.

Alternatives and integrations

If you use NGINX Plus (commercial) or additional modules, you can integrate NGINX with external identity providers. Examples include the NGINX JavaScript module (njs), OpenID Connect integrations, or vendor-specific modules. Example: install and enable the njs module (package names vary by distribution):

# Example installation commands (package names differ between distros)
sudo apt install nginx-plus-module-njs
# OR
sudo yum install nginx-plus-module-njs

# And then load the module in nginx.conf
load_module modules/ngx_http_js_module.so;

Use the appropriate module and configuration for your chosen identity provider or auth flow.

Summary

This lesson showed how to:

Protect a single NGINX location (/admin) using Basic Auth with auth_basic and a .htpasswd file.
Create APR1-encrypted credentials using openssl passwd -apr1.
Extend protection to the entire site.
Consider alternatives for production deployments (OAuth, OpenID Connect, NGINX modules).

Links and references

NGINX auth_basic documentation: https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html
openssl passwd manual: https://www.openssl.org/docs/man1.1.1/man1/openssl-passwd.html
NGINX documentation: https://nginx.org/en/docs/
NGINX Plus: https://www.nginx.com/products/nginx-plus/

Introduction

Install & Config

Intermediate Config

Security

Performance

Conclusion

Demo Authentication

Update the NGINX server configuration

Create the `.htpasswd` file and add a user

Test and reload NGINX

Protecting the entire site

Alternatives and integrations

Summary

Watch Video

Practice Lab

​Update the NGINX server configuration

​Create the .htpasswd file and add a user

​Test and reload NGINX

​Protecting the entire site

​Alternatives and integrations

​Summary

Watch Video

Practice Lab

Update the NGINX server configuration

Create the `.htpasswd` file and add a user

Test and reload NGINX

Protecting the entire site

Alternatives and integrations

Summary