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:
<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 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:
<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.
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:
AuthType WebAuth
require privgroup stanford:stanford
require privgroup stanford:administrative
There currently is no way to require that a user be a member of multiple separate privilege groups to be granted access.
