Quick Nav
See Also
Authorization
Authorization is the process by which a client's identity is verified before gaining access to documents. Authorization is essential when you have content that you wish to protect and provide only to specific approved clients.
Appweb implements a powerful and flexible authorization mechanism that supports both the Basic and Digest authorization schemes prevalent in most browsers. It employs a unified user account and user group database for easy configuration.
HTTP-Based Authentication
Basic and Digest authentication are HTTP protocol mechanisms defined by the HTTP/1.1 specification. Because they operate at the protocol level, they offer a low level of capability and flexibility. When a user attempts to access secured content, the browser displays a generic pop-up dialog box to prompt for the user's credentials. On the server, Appweb consults generic (not application specific) user password files. While these can be customized via VirtualHost and Directory directives, sometimes applications need to apply an application-level user login mechanism. Such login facilities are defined at the application level using session state storage and cookies and are beyond the scope of this document. The Ejscript web application framework is ideal for such application level authentication.
Basic Authentication
Basic authentication was the original HTTP/1.0 authentication scheme. It transmits user names and passwords using a trivial encoding that is no better than using plain text.
SECURITY WARNING: You should not use Basic Authentication if at all possible. Use Digest authentication instead if it is supported by your clients.
Basic Authentication Directives
Appweb basic authorization is controlled by configuration file directives that may be used inside a Directory or VirtualHost block, or within the Default server configuration.
<Directory $DOCUMENT_ROOT/acme> AuthType basic AuthName "Acme Inc" AuthUserFile users.db Require valid-user </Directory>
This example restricts access to the "/acme" directory and all sub-directories to users whose username and password are validated against the user.db password file.
The AuthType directive specifies that basic authorization is being used. The AuthName directive specifies the realm of access to Appweb. The AuthUserFile directive specifies the location of the user password file. You may use a single password file for all authorization, or you can use different files for each authorization section.
User passwords are defined for a user account / realm combination. To create passwords, see the section below that describes the httpPassword utility.
The Require directive controls how users are validated. There are three possibilities for validating users: by group name, by user id or by any valid user name. The associated directives are:
- Require group groupName ...
- Require user userid ...
- Require valid-user
SECURITY WARNING: it is essential that the AuthUserFile and the AuthGroupFile be stored outside the DocumentRoot or any directory serving content.
Digest Authentication
The Digest authentication scheme is a modern replacement for the Basic authorization scheme. It uses cryptographic techniques to encode passwords and does not transmit sensitive information in clear-text.
Digest Authentication Directives
Appweb digest authorization is controlled by configuration file directives that may be used within any Directory, VirtualHost block or within the Default server configuration.
<Directory $DOCUMENT_ROOT/acme> AuthType Digest AuthName "Acme Inc" AuthUserFile users.db Require use roadRunner </Directory>
This example restricts access to the "/acme" directory and all sub-directories to users whose username and password are validated against the designated user.db password file. The essential differences between this example and the Basic authorization example is the AuthType directive.
httpPassword
The httpPassword program is used to create user passwords in a nominated password file. Appweb uses the same authorization file and format for Digest and Basic authentication. This simplifies administration. The file format is:
coyote:Realm:EncryptedPassword
The httpPassword will create and modify such entries in the password file.
The Realm is the name used in the AuthName directive. The EncryptedPassword is an MD5 secure hash of the user name, realm and password.
The command line syntax for httpPassword is:
httpPassword [-c] [-p passWord] userFile realm userName
The userFile parameter specifies the name of the user password file. The userName is the name of the user. If the -p password option is not used, httpPassword will prompt for the password. The -c option will cause httpPassword to create the password file, otherwise it will update the nominated userFile.
SECURITY WARNING: it is essential that the AuthUserFile and the AuthGroupFile be stored outside the DocumentRoot or any directory serving content.
Belt and suspenders
The public Internet is not a friendly place anymore, if it ever was. It is important to take adequate precautions and secure your web content with appropriate authorization and encryption.
An ideal combination is Digest authentication to authorize users, and the SSL protocol to authenticate servers. Using both techniques is the proverbial "belt and suspenders".