Different URLs within a realm can be protected in different ways, with different sets of credentials being valid for different locations. However, since the realm is the key the client uses to remember which credentials to send, being blatant about using multiple sets of credentials within the same realm tends to annoy users when they have to re-authenticate repeatedly for what looks like (and in fact is) the same realm. It's generally a good idea to have a one-to-one relationship between realms and sets of authorized credentials.

But how do you turn on access control in the first place? Just as you apply any other Apache directive: by having the directives appear in the appropriate scope. For example:

    <Directory /usr/local/web/htdocs/finance>
        AuthName Finance
        AuthType Basic
        AuthUserFile /usr/local/web/apache/auth/.htpasswd-finance
        Require valid-user
    </Directory>

This will protect the finance subdirectory and all files and subdirectories in it any below it. Other directories, such as products, remain unaffected.

<Directory> containers are all very well, but what if you want to protect only a single file? Or perhaps a document that isn't mapped to the filesystem, like the output from mod_status? The answer remains the same: use the appropriate scoping directives (such as <Files> and <Location>) to apply the security measures to the items you want protected.

Inheritance
Like almost all other Apache configuration details, the security directives that apply to a particular document or directory may be inherited from the parent, or possibly even further up the tree. This means that at each level you need only supply those directives that are different. The following two fragments are equivalent:

    <Directory /usr/local/web/htdocs/finance>
        AuthName "Finance Department"
        AuthType Basic
        AuthUserFile /usr/local/web/apache/auth/.htpasswd-finance
        Require valid-user
    </Directory>
    <Directory /usr/local/web/htdocs/finance/strategy>
        AuthName "Finance Department"
        AuthType Basic
        AuthUserFile /usr/local/web/apache/auth/.htpasswd-finance
        Require user susan bob
    </Directory>

    <Directory /usr/local/web/htdocs/finance>
        AuthName "Finance Department"
        AuthType Basic
        AuthUserFile /usr/local/web/apache/auth/.htpasswd-finance
        Require valid-user
    </Directory>
    <Directory /usr/local/web/htdocs/finance/strategy>
        Require user susan bob
    </Directory>

The second fragment takes advantage of the inheritance of the values from the parent directory, and simply restricts the access list to only Bob and Susan.

It's generally not a good idea to make too many assumptions when dealing with security matters, so even though inheritance can seem to make your life easier by not requiring you to duplicate directives all over the place, this might be an illusion. Just wait until you see how complicated your life becomes when all the inherited values become compromised because of a single mistake at a higher level.

A related subject involves determining which of possibly several access control modules has the Final Say on whether access is granted or not.

Requiring a Specific Username
Whereas the AuthUserFile directive and friends tell Apache (and the security modules) where to find the authentication databases, it's the Require directive that provides the instructions on how to use them. If a scope doesn't include (or inherit) a Require directive, then it isn't under discretionary access control regardless of whatever other directives may be present.

Multiple occurrences of Require are cumulative; each line gets added to the list of conditions. Whether processing stops at the first matching condition or if all of them need to be met is up to the module programmer; for mod_auth, for example, the first match satisfies the condition for access, even if the configuration contains something potentially confusing like:

    AuthUserFile /home/foo/.htpasswd-foo
    Require user foo
    Require user bar

In this case (and in most cases, in fact), the intended meaning is, "Require the username to be foo OR bar."

To avoid complicated configuration files when the access list is large, there's a shortcut notation: "Require valid-user". This means, "any of the usernames in the authentication database can access this realm." Obviously this won't work unless the database contains credentials only for users allowed access; if there are any users in it which aren't supposed to have access (such as might happen if you're sharing a single database across multiple realms), you'll need to use grouping or some other mechanism because the valid-user keyword won't grind finely enough.

Even though the Require directive isn't specific to any particular module, the syntax of the command is. That means that there aren't any restrictions on the syntax; "Require candy-type caramel" will be accepted, on the grounds that one of the security modules will understand what it means.

Most of the discretionary control modules also provide support for grouping users together, and granting access to groups rather than individuals. This can be done (for mod_auth) with the AuthGroupFile directive. Like the user file, the group file simply contains lines of text. Each line consists of a group name, a colon, and a list of comma-separated usernames. When the username is decoded from the request credentials, the module can look it up in the group file to see to which group(s) it belongs. Here's an example group file:

    board:annette,bill,james,gwynyth
    finance:susan,steve,phoebe,zoe,bill_s
    engineering:geekboy,lisa,melanie,george,j_johnson

To allow access by group, you simply change the Require directive to something like this:

   Require group board

As with normal UNIX users, a single username may belong to multiple groups.

Next: The Standard Apache Security Modules »