Authentication Directives (Apache: The Definitive Guide)

5.2. Authentication Directives

From Apache v1.3 on, filenames are relative to the server root unless they are absolute. A filename is taken as absolute if it starts with "/" or, on Win32, if it starts with "drive :/". It seems sensible to us to write them in absolute form to prevent misunderstandings. The directives are as follows.

5.2.1. AuthType

AuthType type
Directory, .htaccess

AuthType specifies the type of authorization control. Until recently, Basic was the only possible type, but Apache 1.1 introduced Digest, which uses an MD5 digest and a shared secret. As far as we know, no browser yet supports it.

If the directive AuthType is used, we must also use AuthName, AuthGroupFile, and AuthUserFile.

5.2.2. AuthName

AuthName auth-realm
Directory, .htaccess

AuthName gives the name of the realm in which the users' names and passwords are valid. If the name of the realm includes spaces, you will need to surround it with quotation marks:

AuthName "Jack and Jill"

5.2.3. AuthGroupFile

AuthGroupFile filename
Directory, .htaccess

AuthGroupFile has nothing to do with the Group webgroup directive at the top of the Config file. It gives the name of another file that contains group names and their members:

cleaners: daphne sonia
directors: bill ben

We put this into ... /ok_users/groups and set AuthGroupFile to match. The AuthGroupFile directive has no effect unless the require directive is suitably set.

5.2.4. AuthUserFile

AuthUserFile filename

AuthUserFile is a file of usernames and their encrypted passwords. There is quite a lot to this; see the section "Passwords" later in this chapter.

5.2.5. Limit

<Limit method1 method2 ...>
...
</Limit>

The <Limit method> directive defines a block according to the HTTP method of the incoming request. Generally, it should not be used unless you really need it (for example, if you've implemented PUT and want to limit PUTs but not GETs), and we have not used it in site.authent. Unfortunately, Apache's online documentation encouraged its inappropriate use, so it is often found where it shouldn't be.

method defines an HTTP method; see the HTTP/1.1 specification for a complete list. For instance:

<Limit GET POST>
... directives ...
</Limit>

This directive limits the application of the directives that follow to scripts that use the GET and POST methods. Generally speaking, as we have said, there is little need to use Limit. One situation in which you might is if you had a web site where the clients were allowed to write data to your pages: you might want to allow GET/HEAD but restrict PUT/DELETE.

5.2.6. Require

require [user user1 user2 ...] [group group1 group2] [valid-user]
Directory, .htaccess

The key directive that throws password checking into action is require.

The last possible argument, valid-user, accepts any users that are found in the password file. Note: Do not mistype this as valid_user, or you will get a hard-to-explain authorization failure when you try to access this site through a browser, because Apache does not care what rubbish you put after require. It interprets valid_user as a username. It would be nice if Apache returned an error message, but require is usable by multiple modules and there's no way to determine (in the current API) what values are valid.

We could say:

require user bill ben simon

to allow only those users, provided they also have valid entries in the password table, or we could say:

require group cleaners

in which case only sonia and daphne can access the site, provided they also have valid passwords and we have set up AuthGroupFile appropriately.

The block that protects ... /cgi-bin could safely be left out in the open as a separate block, but since protection of the ... /salesmen directory only arises when sales.butterthlies.com is accessed, we might as well put the require directive there.

5.2.7. Satisfy

satisfy [any|all]
Default: all
Directory, .htaccess

Sets access policy if both allow and require are used. The parameter can be either all or any. This directive is only useful if access to a particular area is being restricted by both username/password and client host address. In this case, the default behavior (all) is to require the client to pass the address access restriction and enter a valid username and password. With the any option, the client will be granted access if it either passes the host restriction or enters a valid username and password. This can be used to let clients from particular addresses into a password-restricted area without prompting for a password.

For instance, we want a password from everyone except site 1.2.3.4:

<usual auth setup (realm, files etc>
require valid-user
Satisfy any
order deny,allow
allow from 1.2.3.4
deny from all