User Authentication and Authorization with WebAuth

Activating general authentication in a WebAuth server is as simple as adding the following two lines:

    AuthType WebAuth
    Require valid-user

in the appropriate part of the WebAuth server configuration file. This will require that all accesses to that portion of the web server be authenticated using WebAuth.

Authentication controls for WebAuth match the basic authentication controls within Apache. Control directives can be asserted from within Location and Directory containers. For example, to require WebAuth authentication for all documents being served from a WebAuth server, put:

    <Location "/">
        AuthType WebAuth
        require valid-user
    </Location>

or:

    <Directory "/webroot/">
        AuthType WebAuth
        require valid-user
     </Directory>

into the server configuration file. The difference between these two forms is that the former protects the / URL and everything below it, whereas the latter protects the documents stored in the local directory /webroot and everything below it. Whether you want to specify your access restrictions by URL or by directory is entirely up to you; which is more convenient will depend on what you're serving through your web server.

Just as with basic authentication directives in Apache, the WebAuth restrictions apply recursively through the document tree. In other words, a block like:

    <Location "/private/">
        AuthType WebAuth
        require valid-user
    </Location>

protects not only the URL /private/ but also /private/papers/ or /private/papers/2003.html, but not /private.html. In other words, the access restrictions apply to anything at or below the protected URL or directory.

Just as with basic authentication in Apache, the require directive can be also placed into an access control file (typically a file named .htaccess within most server configurations) within the document tree that the server is serving. For example, the entire server could be set up to require authentication (see above) but further restrictions could be placed on file access within a sub-directory.

To limit access to files in or below the directory /webroot/personal/jdoe to only jdoe, put the following in a file named .htaccess (assuming a default Apache configuration) in /webroot/personal/jdoe:

    AuthType WebAuth
    require user jdoe

Any user id other than jdoe attempting to access files in the /webroot/personal/jdoe directory (or any subdirectories below it) will be forbidden access.

The require directive will also work in combination with host/domain directive controls. This allows for access to be granted either based on from what machine the user is browsing (host/domain identification) or from the user's WebAuth credentials. This is done using the standard Apache "satisfy" directive.

For example, to limit access to the directory /webroot/personal/jdoe so that jdoe can access those files from anywhere OR anyone can access the files within that directory if they're coming from a stanford.edu system, put the following in a file named .htaccess in /webroot/personal/jdoe:

    AuthType WebAuth
    require user jdoe
    order deny,allow
    deny from all
    allow from stanford.edu
    satisfy any

The first two directives work the same as above. The next two lines are set a default policy to deny all access to that directory unless some other access rule permits access. "allow from stanford.edu" allows all access to that directory from any system whose IP address resolves in DNS to a stanford.edu hostname. Finally, "satisfy any" says that if any access rule succeeds, the user should be allowed access.

Without the "satisfy any" line, the user would have to BOTH be coming from a stanford.edu system AND authenticate as jdoe. "satisfy any" grants access if either of those conditions are satisfied.

Another common pattern is:

    AuthType WebAuth
    require valid-user
    order deny,allow
    deny from all
    allow from stanford.edu
    satisfy any

which is the same as the previous one, but which allows any authenticated user to access the content. This configuration can be used to provide light protection for content that should be restricted to only Stanford affiliates.

It's important to remember that a wide variety of people may have access to systems within a particular domain, and that particularly at Stanford, many people have access to stanford.edu systems who are not necessarily closely affiliated with the university. These sorts of access restrictions are therefore only suitable for resources that only require very light protection.

If all of that just confused you, don't worry too much. It's not necessary to understand all the details of how this recipe works in order to use it. For more detailed information and more examples, see the Apache manual; all of this works exactly the same way as it does with a completely stock Apache server except that the user identity is established using WebAuth instead of some other authentication mechanism.

Copyright 2009
    The Board of Trustees of the Leland Stanford Junior University

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.