3 Steps to Basic Authentication with Docker+Nginx

When we needed to implement HTTP Basic Authentication in our application, we required a test environment to validate the Basic Authentication code.

As a result, we established a page for Basic Authentication on a web server containerized with Docker.

There are three steps required to enable Basic Authentication.

  1. Set up a web server.
  2. Create the password file.
  3. Set the URL for Basic authentication.

STEP 1 Setup a web server

Let’s set up a web server. The web server will be a containerized Nginx with Docker; see the following article for details on how to run Nginx in Docker.

You also need to edit the Nginx configuration file, so please copy nginx.conf and default.conf from the container to the same folder as the Dockerfile, referring to the following article.

We want the URL to authenticate as http://localhost:8080/autharea, so we create a content-home/autharea/index.html file. Since it is sufficient to confirm that the connection has been made, the content is as follows.

<!DOCTYPE html>
<html lang="ja">
	<meta charset="utf-8" />
	<title>Authorized Area</title>
	<p>Here is an Authorized Area.</p>

STEP 2 Create the password file

Basic authentication requires a password file containing the account information; when building the Docker image, a script that generates the password file should be copied into the container and executed.

About a password file

The password file, saved in /etc/nginx/.htpasswd, follows the text file format below.


Write an account per line. Also, instead of writing the password in plain text, write the hash calculated by openssl as follows.

% openssl passwd -crypt Password

Script to generate the password file

Create a script to generate a password file: In the same folder as the Dockerfile, create the file gen_htpasswd and enter the following script.


CRYPTPASS=`openssl passwd -crypt ${PASSWD}`

echo "${USER_NAME}:${CRYPTPASS}" >> /etc/nginx/.htpasswd

This script generates an account using testuser as the username and testpass as the password.

Run the password file generation script

Ensure that the script is executed when the Docker image is built. Enter the following code in the Dockerfile created in STEP 1.

FROM nginx:1.23

COPY nginx.conf /etc/nginx
COPY default.conf /etc/nginx/conf.d
COPY gen_htpasswd /etc/nginx

RUN apt update
RUN apt install -y openssl

RUN /etc/nginx/gen_htpasswd

The following section was added to the file created in STEP 1.

COPY gen_htpasswd /etc/nginx

RUN apt update
RUN apt install -y openssl

RUN /etc/nginx/gen_htpasswd

The following processes are performed.

  1. Copy the gen_htpasswd file into the /etc/nginx directory.
  2. Install openssl using apt.
  3. Run the copied gen_htpasswd.

STEP 3 Set the URL for Basic authentication

Set the URL for Basic authentication. Add location /autharea after location / in the default.conf file created in STEP 1.

server {
# Omission

    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
    location /autharea {
    	root	/usr/share/nginx/html;
    	index	index.html index.htm;
    	auth_basic	"Restricted";
    	auth_basic_user_file	/etc/nginx/.htpasswd;

# Omission

/autharea is the URL to be authenticated. In this example, the following URLs are to be authenticated.


For instance, if /autharea is set to /member, the following URLs are subject to authentication.



Run the container and try it out. The container created in STEP 1 builds an image via docker-compose as follows.

% docker-compose build

Once the image is built, run the container.

% docker-compose up -d

When you navigate to http://localhost:8080/autharea/ using a web browser, an authentication dialog should appear.

Basic authentication dialog in Safari
Basic authentication dialog in Safari

Try logging in with an account other than the one you created. After confirming that an error occurs and you are rejected, try logging in with the account you created. You will be able to log in.

Let's share this post !