Return CGI Library

Shortcuts

• Link into the secure area.
• Link to a copy of the .htaccess file.
• Link to a copy of the password file.
• Jump to the FORM documentation.
• Jump to the Usage Points documentation.

Introduction:

Sometimes you don't want the whole world to be able to see parts of your website. Often you can accomplish this by not linking into the area you want to hide, but that is insecure.

Password Protection.

Most browsers support "basic" user authentication via passwords. This isn't a secure protocol as the password is sent in a trivially encoded manner, but that doesn't really matter if done on a secure (SSL) connection.

At Baremetal this password protection is directory based. That is, all files in and below a "protected" directory are password protected. Any access to them requires that the browser provide a valid userid and password.

Setting up password protection at BareMetal.

Without this gadget, setting up password protection is fairly simple. There are (the directory and) two files to be created: the .htaccess file, and the actual file that stores the userids and encrypted passwords (the password file). The trouble occurs when you try to maintain the password file :-)

With our pass_gadget tool, setup is somewhat more complicated, but maintenance is trivial :-).

The less complicated approach is to use create the password file using http://baremetal.com/cgi-bin/mkpasswd and either build your own .htaccess file or use the customization script in step 2 to help you (but ignore the parts about admin password, they are only applicable to the pass_gadget.

We need 5 items:
a FORM that talks to the gadget,
a directory to put the protected files in,
the .htaccess file,
the file to store the passwords in, and
a file to hold the encrypted administrator password [which gets set when you first use the form].

It is not that bad... one just has to look after ALL the details.

1. Create the directory. It can have any name and be located anywhere. Hopefully you use directories to organize your files so you're already familiar with this.
   
   
2. Create the .htaccess file. This file needs to go in the directory that you created in the previous step. It literally HAS TO BE called ".htaccess" That leading period is important.
   
   If you fill in your domain name in the following form, you'll be sent to a CGI script on your webserver that will help you figure out what goes into your .htaccess file, as well as doing some basic testing to find out if you've got your files and directories setup correctly... :-)
   
   
   Enter your domain name:
   
   
   If you'd rather skip running that script, then here's a sample file that comes fairly close to what you'll need:
   
   

   AuthUserFile /home/tbrown/demo.pwd
   AuthName     "secure area"
   AuthType     Basic
   require      valid-user
   

   
   
   
3. (Halfway there!) this is combined with the next step...
   
   
4. For security reasons the gadget won't create either the password file, or the administrator password file. This means you need to upload EMPTY files to fill this role. Both of these files MUST be in your home directory (i.e. the directory above your top level HTML file). You get to pick the password file name, and the administrator password file has the same name except with .passwd added on (UNIX allows you to have file names with multiple periods in them). [Anyone still awake?]
   
   Update: The empty file requirement has been reduced to a file with less than 13 bytes of data in it... Many folks were having trouble uploading "empty" files... they usually ended up being one or two bytes long.
   
   In this example, the password file was called demo.pwd and was in tbrown's home directory (full path is /home/tbrown/demo.pwd). That means that the administrator password will be stored in demo.pwd.passwd.
   
   [If you get one of these steps wrong, the gadget will tell you where it thought things went wrong. ]
   
   So you're wondering what the administrator password is, and how it gets set? Lets cover that later :-), we're in step by step mode right now....
   
   
5. The Form... :-)
   
   Everybody say oohh... This is likely the toughest part. Let's put the HTML for the form up, and then the actual form OK? (Yeah, I know you don't have any choice in the matter... humor me, it is getting late :-)
   
   

   <FORM action="/cgi-bin/pass_gadget" method="post" >
   <input type="hidden" name="adminid" value="tbrown" />
   <input type="hidden" name="file" value="demo.pwd" />
   <PRE>
           password: <input type="password" name="adminpasswd" />
   
   userid to change: <input type="text" name="userid" />
             action: <select name="action" >
   <option selected="selected"> Add </option>
   <option> Delete </option>
   <option> List </option>
   </select>
   For add only:
      user password: <input type="password" name="pass1" />
             verify: <input type="password" name="pass2" />
   </pre>
   <input type="submit" value="continue" />
   </form>
   

   
   
   OK. That's sufficient for your form. Note that there are hidden variables for adminid and file. You could leave them as type=text values, but why bother? For most folks they won't change. (And it makes the example seem simpler to use.)
   
   So... here's the form. Give it a try!
   
   

           password:  (admin password = demo)
   
   userid to change: 
             action: 
   		Add 
   		Delete 
   		List 
   		
   For add only:
      user password: 
             verify: 
   

   
   There have been some questions about what to do with this form you've created (e.g. where to put it and what to call it). The answer is fairly simple: put it somewhere on your site (any directory, under any name -- once you actually create a userid/password pair, you can even move it into the password protected area). The logic is fairly simple. This gadget maintains a file of passwords, and the information about that file is stored in the form. It is not directly related to your password protected area. The .htaccess file you create to restrict access "happens" to point to the same file -- that's the only connection between the secure area and the admin gadget.
   
   
6. Hang on, he said 5 steps... not 6. That's right. You're done. Now test it!
   
   

The form: more detail.

OK, so what's in that form and what makes it tick? Well, there's a CGI program that makes it tick (/cgi-bin/pass_gadget). And the form hands 7 variables to that CGI program to get it to do its magic.

Usage Points

How does the administrator password get set? The first time the script runs, the administrator password file is empty... The script notices this and writes the encrypted administrator password into the file.

How do I change the administrator password? What you want polished gadgets?!!? Overwrite the administrator password file with an empty file, and then re-initialize it as described in the previous point.

How do I change a user's password? Just add the user again. The CGI program will just over-write the old password with a new one.

How do I list the users in the password file? Select the List option! [It is new... that's why this item is still here...]

As a footnote. Under Apache 2.4 you can protect SOME of the files in a directory like this:

<FilesMatch "file1.html|file2.html|thirdfile.jpg">

AuthName "Restricted Area"
AuthType Basic
AuthUserFile /home/userid/subdir/.htpasswd
Require valid-user

</FilesMatch>