WebAuth User Authentication

The Basics

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 or to a
.htaccess file. This will require that all accesses to that
portion of the web server be authenticated using WebAuth.

If your web server is serving as the front-end to an application that does
its own authorization and access control, this may be all you need. The
above configuration will cause Apache to set the REMOTE_USER environment
variable in any CGI process it runs (and also make that information
available to PHP or Java), and the application can take the username from
that variable and do whatever access control checks it needs to do.

If you want Apache to do access control itself, such as when you're
protecting static web pages or an application that doesn't do its own
access control, read on.

Requiring Authentication

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:

into the server configuration file. The difference between these two
fragments 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:

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.

Limiting Accesses

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.

By default, Apache 2.0's configuration does not allow .htaccess files to
override authentication settings for a particular directory. If you want
to use .htaccess files, you need to change the configuration so that the
line:

AllowOverride None

in the configuration block for the server document directory instead
reads:

AllowOverride AuthConfig

Assuming you have done that, 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.

Limiting Access by Group

Since WebAuth uses Apache's normal access control mechanism, you can use
Apache's normal access group support while still using WebAuth to do the
authentication. For example, you could use the following configuration
fragment:

AuthType WebAuth
AuthGroupFile /web/groups
require group admin

and then, after the user is authenticated via WebAuth, they will only be
granted access if their username is a member of the admin group defined
in /web/groups.

For more information on how Apache access groups work, see the Apache
AuthGroupFile and
require
documentation.

Limiting Access by Domain

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.

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.

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.

Limiting Access by Privilege Group

When the mod_webauthldap module is
also used, WebAuth can also limit access to only those users with a
particular attribute in their directory entry. At Stanford, this sort of
directory attribute is called a privilege group. Most privilege groups in
Stanford's directory servers are created from workgroups, managed by users
via Workgroup Manager. Stanford
users should see the
workgroup documentation for more information.

Several other system-maintained privilege groups describing University
communities may also be used (such as the stanford:stanford
and stanford:administrative groups appearing in the examples
below); descriptions of those groups also appear in the
workgroup documentation.

Stanford users who wish to use mod_webauthldap will need to request
directory access permissions for the webauth/<system>.stanford.edu
principal for their server. See the
directory access request page for more information. To be able to
restrict access based on a privilege group, request compare access to
the suPrivilegeGroup attribute. The easiest way to do this is generally
by requesting either WebAuthGeneral or WebAuthPrivileged access.

Users at other sites should see the mod_webauthldap manual for more information about the required directory
attributes.

The syntax for restricting access by privilege group is similar to the
normal Apache syntax for restricting access by group, except rather than
using require group, use require privgroup. For example,
the following configuration:

AuthType WebAuth
require privgroup stanford:stanford

will limit access to users who are members of the stanford:stanford
privilege group (who, in other words, have a directory attribute with the
name defined by the WebAuthLdapAuthorizationAttribute configuration
parameter that has, as its value, stanford:stanford). To allow
someone in one of several groups to access this portion of the web site,
you can include multiple require privgroup lines, such as: