Restricting access with HTTP Basic authentication

In This Section

Introduction
Prerequisites
Creating a Password File
Configuring NGINX and NGINX Plus for HTTP Basic Authentication
Combining Basic Authentication with Access Restriction by IP Address
Complete Example

Introduction

You can restrict access to your website or some parts of it by implementing a username/password authentication. Usernames and passwords are taken from a file created and populated by a password file creation tool, for example, apache-2 utils.

HTTP basic authentication can also be combined with other access restriction methods, for example, restricting access by IP address or by geographical location.

Prerequisites

NGINX Plus or NGINX Open Source
Password file creation utility, for example, apache2-utils

Creating a Password File

To create username-password pairs, use a password file creation utility, for example, apache2-utils.

Verify that apache2-utils are installed.
Create a password file and a first user. Run the htpasswd utility with the -c flag and type-in the path to the file as the first argument, and the user name as the second argument:
```
$ sudo htpasswd -c /etc/apache2/.htpasswd user1
```
When you press Enter, you will be prompted to type-in a password for user1 twice.
In the same way create other user-password pairs. In this case, you do not have to provide the -c flag:
```
$ sudo htpasswd /etc/apache2/.htpasswd user2
```

When finished, you can view the contents of the file:

$ cat /etc/apache2/.htpasswd

The file contains a username and the encrypted password for each record:

user1:$apr1$/woC1jnP$KAh0SsVn5qeSMjTtn0E9Q0

user2:$apr1$QdR8fNLT$vbCEEzDj7LyqCMyNpSoBh/

user3:$apr1$Mr5A0e.U$0j39Hp5FfxRkneklXaMrr/

Configuring NGINX and NGINX Plus for HTTP Basic Authentication

Inside a location that you are going to protect, specify the auth_basic directive and give a name to the password-protected area. The name of the area will be shown in the username/password dialog window when asking for credentials:
```
location /status {                                       
    auth_basic “Administrator’s Area”;
    ....
}
```

Specify the auth_basic_user_file directive with a path to the .htpasswd file that contain user/password pairs:

location /status {                                       
    auth_basic           “Administrator’s Area”;
    auth_basic_user_file /etc/apache2/.htpasswd; 
}

Alternatively, you you can limit access to the whole website with basic authentication but still make some website areas public. In this case, specify the off parameter of the auth_basic directive that cancels inheritance from upper configuration levels:

server {
    ...
    auth_basic           "Administrator’s Area";
    auth_basic_user_file conf/htpasswd;

    location /public/ {
        auth_basic off;
    }
}

Combining Basic Authentication with Access Restriction by IP Address

HTTP basic authentication can be effectively combined with access restriction by IP address. You can implement at least two scenarios:

a user must be both authenticated and have a valid IP address
a user must be either authenticated, or have a valid IP address

Allow or deny access from particular IP addresses with the allow and deny directives of the nignx access module:
```
location /status {
    ...
    deny 192.168.1.2;
    allow 192.168.1.1/24;
    allow 127.0.0.1;
    deny all;
}
```
Access will be granted only for the 192.168.1.1/24 network excluding the 192.168.1.2 address. Note that the allow and deny directives will be applied in the order they are defined.
Combine restriction by IP and HTTP authentication with the satisfy directive.
If you set the directive to to all, access is granted if a client satisfies both conditions. If you set the directive to any, access is granted if if a client satisfies at least one condition:
```
location /status {
    ...
    satisfy all;    

    deny  192.168.1.2;
    allow 192.168.1.1/24;
    allow 127.0.0.1;
    deny  all;

    auth_basic           "Administrator’s Area";
    auth_basic_user_file conf/htpasswd;
}
```

Complete Example

The example shows how to protect your status area with simple authentication combined with access restriction by IP address:

http {
    server {
        listen 192.168.1.23:8080;
        root   /usr/share/nginx/html;

        location /status {
            status;
            satisfy all;

            deny  192.168.1.2;
            allow 192.168.1.1/24;
            allow 127.0.0.1;
            deny  all;

            auth_basic           “Administrator’s area;
            auth_basic_user_file /etc/apache2/.htpasswd; 
        }

        location = /status.html {
        }
    }
}

If you type the address that corresponds to your status page, first, you will get the password prompt:

If the provided name and password will not match the ones from the password file, you will get the 401 Authorization Required error.