// Tutorial //

How To Set Up Basic HTTP Authentication With Nginx on Ubuntu 14.04

Published on February 22, 2016
Default avatar
By finid
Developer and author at DigitalOcean.
How To Set Up Basic HTTP Authentication With Nginx on Ubuntu 14.04

Introduction

Nginx is one of the leading web servers in active use. It and its commercial edition, Nginx Plus, are developed by Nginx, Inc.

In this tutorial, you’ll learn how to restrict access to an Nginx-powered website using the HTTP basic authentication method on Ubuntu 14.04. HTTP basic authentication is a simple username and (hashed) password authentication method.

Prerequisites

To complete this tutorial, you’ll need the following:

Step 1 — Installing Apache Tools

You’ll need the htpassword command to configure the password that will restrict access to the target website. This command is part of the apache2-utils package, so the first step is to install that package.

  1. sudo apt-get install apache2-utils

Step 2 — Setting Up HTTP Basic Authentication Credentials

In this step, you’ll create a password for the user running the website.

That password and the associated username will be stored in a file that you specify. The password will be encrypted and the name of the file can be anything you like. Here, we use the file /etc/nginx/.htpasswd and the username nginx.

To create the password, run the following command. You’ll need to authenticate, then specify and confirm a password.

  1. sudo htpasswd -c /etc/nginx/.htpasswd nginx

You can check the contents of the newly-created file to see the username and hashed password.

  1. cat /etc/nginx/.htpasswd
Example /etc/nginx/.htpasswd
nginx:$apr1$ilgq7ZEO$OarDX15gjKAxuxzv0JTrO/

Step 3 — Updating the Nginx Configuration

Now that you’ve created the HTTP basic authentication credential, the next step is to update the Nginx configuration for the target website to use it.

HTTP basic authentication is made possible by the auth_basic and auth_basic_user_file directives. The value of auth_basic is any string, and will be displayed at the authentication prompt; the value of auth_basic_user_file is the path to the password file that was created in Step 2.

Both directives should be in the configuration file of the target website, which is normally located in /etc/nginx/sites-available directory. Open that file using nano or your favorite text editor.

  1. sudo nano /etc/nginx/sites-available/default

Under the location section, add both directives:

/etc/nginx/sites-available/default.conf
. . .
server_name localhost;

location / {
        # First attempt to serve request as file, then
        # as directory, then fall back to displaying a 404.
        try_files $uri $uri/ =404;
        # Uncomment to enable naxsi on this location
        # include /etc/nginx/naxsi.rules
        auth_basic "Private Property";
        auth_basic_user_file /etc/nginx/.htpasswd;
}
. . .

Save and close the file.

Step 4 — Testing the Setup

To apply the changes, first reload Nginx.

  1. sudo service nginx reload

Now try accessing the website you just secured by going to http://your_server_ip/ in your favorite browser. You should be presented with an authentication window (which says “Private Property”, the string we set for auth_basic), and you will not be able to access the website until you enter the correct credentials. If you enter the username and password you set, you’ll see the default Nginx home page.

Conclusion

You’ve just completed basic access restriction for an Nginx website. More information about this technique and other means of access restriction are available in Nginx’s documentation.


Want to learn more? Join the DigitalOcean Community!

Join our DigitalOcean community of over a million developers for free! Get help and share knowledge in our Questions & Answers section, find tutorials and tools that will help you grow as a developer and scale your project or business, and subscribe to topics of interest.

Sign up
About the authors
Default avatar
finid

author

Developer and author at DigitalOcean.

Default avatar
senior technical writer

hi! i write do.co/docs now, but i used to be the senior tech editor publishing tutorials here in the community.


Still looking for an answer?

Was this helpful?

When the Nginx Server is deployed inside a GitLab App (Omnibus), the htpasswd file should be placed elsewhere : so /etc/nginx/ (no such a repertory) should be remplaced by /var/opt/gitlab/nginx/conf/ everywhere in this How To.

Step 1 : the same $ sudo apt-get install apache2-utils

Step 2 :

  • Just change $ sudo htpasswd -c /etc/nginx/.htpasswd nginx by $ sudo htpasswd -c /var/opt/gitlab/nginx/conf/.htpasswd nginx (nginx is the user name)
  • You can check the contents of the newly-created file with $ sudo cat /var/opt/gitlab/nginx/conf/.htpasswd

Step 3 becomes : Updating the GitLab Configuration

  • In this step, you’ll connect the htpasswd file path with GitLab.
  • So edit gitlab.rb file with $ sudo nano /etc/gitlab/gitlab.rb
  • Add the line nginx['custom_gitlab_server_config'] = "auth_basic 'Restricted';\n auth_basic_user_file /var/opt/gitlab/nginx/conf/.htpasswd;\n", then save and quit

Step 4 : Apply the changes and reconfigure GitLab with $ sudo gitlab-ctl reconfigure

While the tutorial says: “sudo nano /etc/nginx/sites-available/default”

If you have already setup your website you should use: “sudo nano /etc/nginx/sites-available/your_site”

If want add a user into htpasswd, just $ sudo htpasswd /etc/nginx/.htpasswd new_user

If I want to except request with param ?wc-api=… How is configuration?