User-based authentication

Adding user-based authentication involves two steps...

• Create a password file containing usernames and passwords
• Add appropriate directives to your dynamic configuration file (.htaccess)

Step 1: Create a password file containing usernames and passwords

The password file used in HTTP authentication is a text file containing pairs of usernames and encrypted passwords, one per line, separated by a colon. It is traditionally named htpasswd The following example illustrates the file format...

admin:oeoJB1X4JXF..
dirk:sOBLxYAjY2Ru2
pratt:Wd8LmSCg63yBE

Notice that the passwords are encrypted, not in plaintext. Passwords in HTTP authentication use the same format as those in the Unix system password file, which are encrypted with the crypt(3) C system call or an equivalent function provided by a language such as Perl. The crypt(3) C function uses the standard DES encryption algorithm to turn plaintext into ciphertext. The encrypted password is always 13 characters long (regardless of the length of your plaintext password) and may be composed of letters, numbers, `/', and '.'. The htpasswd command available on our servers can be used to create password files and add new users. Run it with no arguments from your developer shell account for a usage summary. Windows versions of htpasswd exist, but we have yet to find one whose encrypted passwords that work under Unix.

Here's an example of using the htpasswd command to create a password file in your developer account home directory and add a username...

[joeuser@s1 joeuser] htpasswd
Usage: htpasswd [-c] passwordfile username
The -c flag creates a new file.
[joeuser@s1 joeuser] htpasswd -c htpasswd admin
Adding password for admin.
New password:
Re-type new password:
[joeuser@s1 joeuser] htpasswd htpasswd dirk
Adding user dirk
New password:
Re-type new password:
[joeuser@s1 joeuser] cat htpasswd 
admin:q774.gXiXd.VU
dirk:iEHEDps1Wh8wM

To improve security, you should place your htpasswd file in a directory invisible to your HTTP server, such as your UNIX User home directory or a sibling of your document root directory. However, note that its permissions must allow world reads (but not world writes) because the HTTP server will open it as an unprivileged user. Use the chmod command to set file permissions.

Step 2: Add appropriate directives to your dynamic configuration file

Assume you wish to add user-based authentication to your server's access_reports file directory (a subdirectory of your HTTP server's document root directory named access_reports) and a file named credit-cards.txt in your document root directory. Also assume you wish to use a password file named htpasswd in your UNIX User home directory. The following directives would implement authentication when added to your .htaccess file...

<FILES access_reports>
require         valid-user
AuthType        Basic
AuthName        "Access Reports"
AuthUserFile    /home/joeuser/htpasswd
</FILES>

<FILES credit-cards.txt>
require         valid-user
AuthType        Basic
AuthName        "Credit card numbers"
AuthUserFile    /home/joeuser/htpasswd
</FILES>

These directives perform the following functions...

• The require directive specifies which usernames in the password file can access the protected resource. The valid-user parameter instructs the server to accept any valid username and password that appears in the password file. If you specify the user parameter followed by individual usernames (separated by a space), only those usernames will be able to access the protected resource.

• The AuthType directive specifies the type of authentication that will occur. Basic authentication is the only type which is widely implemented, but this directive exists to support future authentication methods, such as the more secure digest authentication.

• The AuthName specifies what is known as the authorization realm or realm string. This is the text displayed in the dialog box when your browser prompts you for a username and password. The authentication realm is also used by the browser to determine which username and password to send when multiple authenticated resources are accessed in the same browser session.

• The AuthUserFile directive specifies the path to the password file. This must be specified as an absolute path -- if specified as a relative path, the HTTP server will look in its root directory, which is not where your content resides.

The .htaccess file containing these directives would need to be placed in your document root directory because it refers to logs and credit-cards.txt with relative paths. You could place .htaccess in any server-visible directory if you specified the paths to the protected resources by absolute pathname (such as /home/joeuser/www/joeuser/credit-cards.txt).

Here are pointers to documentation on each of the directives used above...

• <Files>
• require
• AuthType
• AuthName
• AuthUserFile

Host-based authentication

Host-based authentication is configured similarly to user-based authentication. You can restrict access by host name (fully-qualified domain name or a subdomain) or IP address (a complete IP address or an IP network).

Assume you want to create an intranet on your Servlets.Net Web site in the subdirectory intranet. Also assume your organization's domain name is sample.org. You want all hosts in your domain to be able to access this resource, as well as all hosts in the IP network 192.168.1, which is outside your domain. You would do so with the following dynamic configuration file directives...

<FILES intranet>
order		deny, allow
deny		from all
allow		from sample.org 192.168.1
</FILES>

The deny and allow directives instruct the server about which hosts should be allowed to access the given resource.

Here are pointers to documentation on each of the directives used above...

• <Files>
• order
• deny
• allow