Password Protecting Your Site with htaccess

The contents of this article may be out of date. It has been archived and will no longer be updated, comments are closed and the page is provided for reference purposes only.

It is sometimes handy to be able to password protect your pages or an entire site. Maybe you're building a new site, but you only want yourself and client to be able to view the work-in-progress. Apache allows you to fairly easily add password protect an entire site, folder or individual file.

This is the login box a Safari user will see when trying to access a site protected with a username and password.

To add password protection to your site we need two things:

1. A text file on your server that will store your username and password.
2. A special file called .htaccess in the folder you want to protect.

Each time I have needed to password protect a site in the past I have ended up searching around for bits of code and password encryptors on various websites. This tutorial brings all the information you will need to one single page.

Creating the password file

The first step is to create a simple text file that will store your username and password, separated by a colon (:). The catch is that the password must be encrypted.

Simply enter your desired username and password into the form above. The form uses javascript so no data is sent over the internet and the password is encryption on your machine. You’ll get back a string similar to the following (The encrypted password is “pass” in the below example):

john:1Es5VfTymIbRY

Now, open up your favourite text editor (e.g. Notepad or TextEdit), then copy and paste the username/password string into the editor. Save the file and call it .htpasswd.

Note: If you are using OS X or Linux you may want to name you file htpasswd.txt, upload it and rename it to .htpasswd when it is on the server. File names starting with a full stop are treated as hidden files by Unix so you may not be able to see it in the finder window.

Next, upload this file to your website.

If possible place the file outside the Web root of your site. For example, place it above your public_html or htdocs folder. If this is not possible don’t worry as Apache is often set up by default to block web-based access to files beginning with .ht and the password is encrypted.

Creating the .htaccess file

Now that you have created and uploaded your password file, you need to tell Apache to use it to protect your page(s) or site. This is what your .htaccess file will do.

Open your text editor again, create a new file, and save it as .htaccess or if you already have a .htaccess file simply add the below code to your existing file.

To password protect a folder on your site, put the following code in your .htaccess file:

AuthUserFile /full/path/to/.htpasswd AuthType Basic AuthName "My Secret Folder" Require valid-user

The above .htaccess file will password protect all files in the folder that it is placed in, and all sub-folders under that folder too. So if you wanted to password protect your entire site, place the .htaccess file in your Web root folder.

/full/path/to/.htpasswd should be the full path to the .htpasswd file that you have just uploaded. The full path is the path to the file from the Web server’s volume root - for example, /home/username/.htpasswd or C:\wwwroot\username\.htpasswd.

Below is a small PHP script that prints the full path to the directory it is placed in. Copy the code and paste it into a file called fullpath.php. You can then upload the file to the directory where you want to place the .htpasswd. Then point your browser to http://www.domain.com/path/to/fullpath.php and the result will give you the path you need.

<?php echo dirname(__FILE__); ?>

Testing it works

Now visit the folder that you’ve protected. You should see a password dialog like the one shown at the start of this tutorial. Type in the username and (unencrypted) password that you chose earlier, and you should be given access to your folder or file!

Note: This type of password protection grants you access to the password protected folder/files until you restart your browser.

Troubleshooting

If the dialog keeps popping up when you enter your credentials, check that you entered the username and password correctly. If it still doesn’t work, check the path to your .htpasswd file on the server is correct. Finally make sure that both the .htpasswd and .htaccess files are readable by the Web server user (chmod 644).

If the password protection isn’t working (i.e. you can still access your stuff without needing to enter a username/password), check that your web server supports .htaccess password protection, it needs to be an Apache server, and your server admin needs to have AuthConfig override enabled for your site.

Password protecting individual files

To password protect a single file in a folder, use the following .htaccess file:

AuthUserFile /full/path/to/.htpasswd AuthType Basic AuthName "My Secret Page"

<Files "mypage.html"> Require valid-user </Files>

This will password protect just the mypage.html file in the folder where you put the .htaccess file.

If you want to password protect more than one file in the same folder, just create more <Files></Files> blocks within the same .htaccess file - for example:

AuthUserFile /full/path/to/.htpasswd AuthType Basic AuthName "My Secret Page"

<Files "mypage.html"> Require valid-user </Files>

<Files "otherpage.html"> Require valid-user </Files>

If you want to password protect other folders (that aren’t under the currently protected folder), simply copy your .htaccess file to the new folder to be protected.

Adding more users

You’re not limited to just one user. If you want to add other usernames and passwords, simply add each new username/password on its own line in your .htpasswd file, e.g.:

john:1Es5VfTymIbRY jane:Wx1WnNB24DiHM

SSH

If you have SSH access to your web server (or you’re running Apache on a local machine) and are happy using the command line, you can encrypt your password and add it to your password file in one go by using the htpasswd utility that comes with Apache. SSH to your server or open up a terminal window on your local machine, cd to the folder where you want to create your password file, and type (john should be replaced with the username you want to use):

htpasswd -c .htpasswd john

You’ll be prompted to enter and retype a password, then the .htpasswd file will be created for you.

You can add extra users with the command:

htpasswd .htpasswd jane

Make sure you don’t include the -c option when adding additional users, or htpasswd will attempt to create a new password file!

Legal Notice The javascript password generator on this page is based on work by JoesWebTools that itself is based on work by John F. Dumas, Eric Young and crypt(3).

This article was posted on 2 July 2010 in Apache, Code, Tutorials

That's the end of this article. I hope you found it useful. If you're enjoyed this article why don't you have a look around the archives, where you can find some more tutorials, tips and general ramblings.