Skip navigation

STANFORD UNIVERSITY

INFORMATION TECHNOLOGY SERVICES

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.

Last modified Wednesday, 11-May-2011 03:46:55 PM

Stanford University Home Page