How nginx basic authentication works

The ngx_http_auth_basic_module module lets you require visitors to enter a correct username and password before they can access web content. This is useful when some content should not be public but still needs to be available to selected people. nginx's HTTP auth and Apache's HTTP auth both fit this kind of access control.

nginx includes ngx_http_auth_basic_module by default. If you do not need it, you can disable it at build time with --without-http_auth_basic_module.

Directives

auth_basic string | off; Default: auth_basic off; Context: http, server, location, limit_except

The default is no authentication. If you provide a string, that string appears in the browser's login dialog.

auth_basic_user_file file; Default: — Context: http, server, location, limit_except

This directive points to the username/password file. Its contents look like this:

testuser1:password1
testuser2:password2:comment

Example configuration

server{
       server_name  www.xiaoten.com xiaoten.com;

        index index.html index.php;
        root /data/site/www.xiaoten.com;

        location /
        {
                auth_basic "nginx basic http test for xiaoten.com";
                auth_basic_user_file conf/htpasswd;
                autoindex on;
        }
}

Pay close attention to the auth_basic_user_file path. If it is wrong, nginx will return 403 again and again.

Creating the password file

You can use htpasswd or openssl.

# printf "test:$(openssl passwd -crypt 123456)\n" >>conf/htpasswd
# cat conf/htpasswd
test:xyJkVhXGAZ8tM

The username is test and the password is 123456.

Reload nginx:

# /usr/local/nginx-1.5.2/sbin/nginx -s reload

Directory protection under LNMP

For an LNMP environment, there is also a script-based way to set up a protected directory. Apache normally uses htpasswd from apache2-utils, but LNMP one-click installs and custom LNMP builds generally do not install that package.

1. Create an htpasswd-style file

Run:

wget -c soft.vpser.net/lnmp/ext/htpasswd.sh;bash htpasswd.sh

Enter the username, password, and authentication filename when prompted. The script generates the authentication file. Record the path it returns, for example:

/usr/local/nginx/conf/vpser.net.auth

2. Add nginx auth configuration

For a directory such as soft under a domain, add this inside the domain's server block:

location ^~ /soft/
{
auth_basic "Authorized users only";
auth_basic_user_file 这里写前面脚本返回的文件路径;
}

Authorized users only is the prompt shown to visitors; you can change it. The auth_basic_user_file value must be the path returned by the htpasswd.sh script. After updating the configuration, restart nginx. Visiting http://yourdomainname/soft/ should then ask for a username and password.

One caveat: after authentication is enabled, PHP files in that directory may no longer be parsed and may be offered as downloads instead. If PHP still needs to run there, change the configuration to:

location ^~ /soft/ {
    location ~ .*\.(php|php5)?$ {
        fastcgi_pass unix:/tmp/php-cgi.sock;
        fastcgi_index index.php;
        include fastcgi.conf;
    }
    auth_basic "Authorized users only";
    auth_basic_user_file 这里写前面脚本返回的文件路径;
}

This approach works for LNMP one-click installs and for LNMP installed manually, though directory and configuration file locations can differ.

After setting it up, test the configuration:

/usr/local/nginx/sbin/nginx -t

Then reload:

/usr/local/nginx/sbin/nginx -s reload