How to properly setup nginx local authentication

Learn How to properly setup nginx local authentication

If you have a website running on nginx and you want to make sure the content is not viewable by anyone that isn’t authenticated, the easiest way to set this up is to setup local authentication.  Let us take a look at how to properly setup nginx local authentication so the security cannot be bypassed.  We say “properly” setup nginx local authentication as there is a mistake that can be made in the nginx configuration that can lead to a major flaw with local authentication leading to content being served inadvertently to anonymous users who are not authenticated.  More on that below.  Read on!


Setting up local authentication in nginx just takes a few steps.  We will use Ubuntu Server as our linux server of choice for the examples that follow.  The first thing that you will need to do is grab a copy of the apache2utils that will enable us to enable the local authentication.

sudo apt-get install apache2-utils

After installing the apache2-utils you will then need to run the following command to create the user you wish to use to secure your website which will create your .htpasswd file containing the authentication information:

sudo htpasswd -c /var/www/website/.htpasswd youruser

You will be prompted for a new password and then to confirm the new password by htpasswd utility.

Nginx Configuration File

As we come to this part of the equation we get to the part that many fail to implement correctly.  Many how to guides out there also show how to implement nginx local authentication and don’t properly place the most important configuration blocks in the right place.

The wrong way

We say wrong way here, because most people who implement basic authentication will want it to be effective for the entire site, not just the root URL, without the possibility of it being bypassed.  Most how to’s will show to  include the auth_basic and auth_basic_user_file under the location section as follows:

location / {
      index  index.html index.htm;
      auth_basic "Restricted";                                
      auth_basic_user_file /var/www/yourwebsite/.htpasswd;  

In the example snippet above above, authentication WILL work (for instance to www.yourwebsite.com), but only to the root URL.  If I know pages on the website, or even guess the general pages that most people have running on a site, when I type a link DIRECTLY to that page, for instance www.yourwebsite.com/about the page will start to load in the background, and THEN will get an authentication popup.  Guess what, if I click cancel, the page continues to load until completed.  Scary!  The reason for this is that we have not specified the local authentication for the entire server block.  A simple change to the above makes all the difference in the world.

The right way

Simply move the authentication directives to live under the server block instead of the location block and we are good:

server {
    auth_basic "Restricted";
    auth_basic_user_file /var/www/website/.htpasswd;

This change will secure your entire website, not just the root URL.  If you try typing in a link directly to a page, you will immediately get the authentication pop up and the page WILL NOT load.  Clicking cancel or otherwise yields the 401 error page.

Subscribe to VirtualizationHowto via Email 🔔

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Brandon Lee

Brandon Lee is the Senior Writer, Engineer and owner at Virtualizationhowto.com and has over two decades of experience in Information Technology. Having worked for numerous Fortune 500 companies as well as in various industries, Brandon has extensive experience in various IT segments and is a strong advocate for open source technologies. Brandon holds many industry certifications, loves the outdoors and spending time with family.

Related Articles

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.