Skip navigation



Upgrading from WebAuth v2

These notes are to assist current users of WebAuth v2 in migrating to WebAuth v3. This is not intended as installation documentation; for that, consult the WebAuth installation guide, also available as INSTALL in the WebAuth source distribution. These notes are likely only of interest to Stanford users, as previous versions of WebAuth were not released outside of Stanford. Most of the comments below are Stanford-specific.

Supported Browsers

WebAuth v3 relies on proper redirect handling in the browser so that when the client is sent to authenticate and then returns to the protected page, the browser will realize that it should retrieve the page again from the server. As of WebAuth 3.2.3 and later, the server does as much as is possible in the HTTP protocol to make sure that the initial redirect isn't incorrectly cached, but some browsers' handling of redirects is exceptionally poor.

The one browser with known problems so far is Internet Explorer 5.0 for the Macintosh (IE for Windows is not affected), which appears to insist on incorrectly caching the redirect in violation of the HTTP protocol no matter what the server does. This is a bug that is fixed in IE 5.1 for the Macintosh, and we strongly recommend that all users upgrade. If a user cannot upgrade, another possible workaround may be to completely disable caching of pages in the browser preferences.

Note that browsers that have a problem with the redirects in WebAuth v3 would probably also have problems with WebAuth v2 sites, since WebAuth v2 used a similar technique. They may not, however, have noticed those problems if they always used S/Ident.

Kerberos v5 and Passwords

WebAuth v3 uses Kerberos v5 rather than Kerberos v4, and this is the direction we are going for all authenticated services. It is one of the first services to switch over, however, and therefore this may be many users' first encounter with Kerberos v5.

We have attempted, over the past five years, to keep all user passwords synchronized between Kerberos v4 and Kerberos v5, but we have encountered several instances where that effort has failed. Users whose Kerberos v5 information is incorrect will be unable to access web sites protected by WebAuth v3. If those users were using a recent version of PC Leland, they would also get warnings about being only partially logged in, but many of these users do not use PC Leland or have not updated it in many years.

Thankfully, most of these problems can be solved by a simple password change, which forces a resynchronization between Kerberos v4 and Kerberos v5. Users who can access other authenticated services but who can't access services protected by WebAuth v3 should first try changing their password using PC Leland, MacLeland, or by logging on to the Unix servers and typing kpasswd at the prompt. If that doesn't work, the user should submit a HelpSU request so that someone can look at the account.

Apache Version and Integration

Webauth v3 is designed to run with Apache 2.0.43 and up, so current users will need to upgrade from using Apache 1.3. There are significant design changes in the Apache server itself, as well as changes to the configuration directives and syntax. These changes are not covered in detail here because they are covered in detail in the Apache documentation. See, for example, Upgrading to Apache 2.0 from 1.3.

WebAuth is now distributed as dynamic modules for Apache, rather than as a custom-built Apache server. This means that you will no longer need to get your Apache server binaries from us, and can instead install Apache yourself in whatever configuration that you need and then install WebAuth built against that Apache server. This also means that you can just follow the standard Apache documentation for all aspects of your server configuration other than the WebAuth module itself.

Srvtabs and Keytabs

WebAuth v3 works with Kerberos v5, as opposed to previous versions of WebAuth which ony supported Kerberos v4. This means that you cannot reuse your ident srvtab and will need to download a keytab. Like a srvtab, a keytab is a binary file that contains the password for a Kerberos identity corresponding to your server, but in this case for a Kerberos v5 key instead.

For WebAuth v2, the server identity was always ident.system. For WebAuth v3, it will always, or nearly always, instead be webauth/ The slash instead of a period and the fully qualified system name are differences between Kerberos v4 and Kerberos v5.

You will still be able to download this keytab using leland_srvtab, the same way that you downloaded the srvtab for WebAuth v2. Details are in the installation documentation.

New Single Sign-On

WebAuth v3 has a new form of single sign-on that works entirely through weblogin. When a user enters their username and password on the weblogin page, a cookie is set that marks this user as "logged into the network" and can be used to generate credentials for other sites without the user needing to log in again. This allows the user to visit various sites protected by WebAuth v3 and not have to enter their username and password again.

When the user closes their browser, their credentials will be destroyed, and the next time they open a browser and go to a site protected by WebAuth v3, they will need to log in via weblogin again. Their credentials will also expire after ten hours.

The user will see a mandatory confirmation page before entering each new WebAuth site, telling them which site they are authenticating to.

Application Logins

After the user logs in via weblogin and returns to the site that they were attempting to access, that WebAuth-protected site sets an additional cookie just for itself. That cookie is then used to authenticate the user to that particular site while the user moves through the site. This cookie is independent of the cookie representing the user's login to the network as a whole.

One implication of this is that the user will have to be more careful about logging out. WebAuth v2 only had the concept of being logged on to a particular application, so if one logged out of all applications one had visited, one was fully logged out. WebAuth v3 has the additional concept of a network login that must also be destroyed before the user is completely logged out. Because of this, we even more strongly recommend that users who wish to log out of WebAuth-protected sites simply close their browser when they're done, ensuring that all of their WebAuth cookies are destroyed. For more information about logging out, see the FAQ on logging out and the FAQ on setting up an application logout page.

Another implication is that applications will have more control over the WebAuth behavior for their application. They can, for example, require the user to enter their username and password again when accessing that application, even if they have already logged on to the network previously. This has already been done in WebAuth v2 for Axess, but it has now been generalized and is available as a configuration directive in the WebAuth server for protected sites that need a higher level of assurance that the user hasn't walked away from their system without logging out.


WebAuth no longer supports S/Ident at all as of 3.3.0. The S/Ident protocol is inherently vulnerable to active man-in-the-middle attacks which are particularly easy to accomplish with a single known central server to which users are authenticating. Since this is exactly the case for, S/Ident support was removed completely even though active man-in-the-middle attacks are not trivial.

The long-term replacement for the single sign-on capabilities of S/Ident is SPNEGO, a protocol for doing Kerberos authentication directly over an HTTPS connection. Some work has already been done to implement this support in WebAuth and it will be deployed at Stanford in the near future.

LDAP Directory Access

Directory support for checking priviledge groups as well as retrieving attributes like name and email is available beginning with the WebAuth 3.1.0 release. This support uses the new OpenLDAP directory service and SASL GSS-API (Kerberos v5) authenticated binds. LDAP functionality is provided by a separate mod_webauthldap module with its own set of directives. See its reference manual for more details.

Access to directory information is now considerably more flexible. Each application may specify which directory attributes they need out of the ones have access to, rather than limiting the directory queries to a hard-coded subset of the available attributes. Information on exaclty which attributes are available and which applications will be eligible for access to them, can be found in the directory project pages.

Configuration Directive Changes

All of the Apache WebAuth configuration directives have changed. Some serve the same purpose before and are mapped in the table below, but others are entirely new. For those mapped below, the values are largely the same; but the old names cannot be used with Webauth v3. Consult the mod_webauth reference manual for the nuances.

Older Versions WebAuth v3
AuthType StanfordAuth AuthType WebAuth
suauthSidentSrvtab WebAuthKeytab
suauthFailAction WebAuthLoginURL
suauthDebug WebAuthDebug
suauthProxyHeader (use mod_headers)
StanfordAuthGroups AuthGroupFile

Note that the URL for the login server (used for WebAuthLoginURL) has changed completely from WebAuth v2, so you cannot just change the name of that directive.

For those using suauthProxyHeader, the equivalent functionality is not supported in WebAuth v3 because mod_headers handles the same thing more flexibly. With mod_headers, you can add arbitrary HTTP headers to proxied requests, including information from environment variables such as the WEBAUTH_ variables. For example, if you want to include the authenticated SUNet ID in an HTTP header called Webauthproxy (like the old WebAuth v2 support), put something like:

    RequestHeader set Webauthproxy "%{WEBAUTH_USER}e"

in your Apache configuration. For more information, see the mod_headers documentation and the documentation on environment variables in the mod_webauth manual and mod_webauthldap manual.

We recommend creating a new WebAuth v3 configuration following the installation instructions and the reference manual instead of reusing your existing WebAuth v2 configuration. However to ease the transition, some backwards compatibility was added as described in the next section.

Backwards Compatibility

Existing configuration of the main server and virtual hosts will need to be changed to the Webauth v3 directives, but some common directives used in .htaccess files, as well as Location and Directory blocks are supported. The presence of Authtype StanfordAuth turns on backwards compatibility. Among other things, the older SU_AUTH_USER environment variable will be set to the username of the authenticated user. The following table details the support for the old webauth directives:

Directive Action
AuthType StanfordAuth Turns on the backwards compatibility features
StanfordAuthDontCache same as WebAuthDontCache
StanfordAuthForceReload same as WebAuthExtraRedirect
StanfordAuthLife same as WebAuthAppTokenLifetime and also enables WebAuthForceLogin
StanfordAuthReturnURL same as WebAuthReturnURL
StanfordAuthConfirmMsg not supported, ignored
StanfordAuthDoConfirm not supported, warning message logged if it's used
StanfordAuthGroups not supported, warning message logged if it's used

Similarly in the case of the LDAP module, only WebAuth v3 directives can be used in the main configuration and virtual host blocks, but .htaccess files and Location and Directory blocks can contain the old-style

    AuthType StanfordAuth
    require group something:something

directives. If the old environment variables for directory information are needed, they can be set by adding the following directives along with AuthType StanfordAuth:

Environment Variable Directive
SU_AUTH_DIRNAME WebAuthLdapAttribute displayName
SU_AUTH_DIRMAIL WebAuthLdapAttribute mail
SU_AUTH_UNIVID WebAuthLdapAttribute suUnivID
SU_AUTH_DIRPRIVS not supported

(These same attributes will set the new WEBAUTH_LDAP_* environment variables if used without AuthType StanfordAuth.)

Environment variables

In normal operation, instead of the older SU_AUTH_USER variable, WebAuth v3 sets WEBAUTH_USER to the authenticated user. Note, however, that both the old and new versions of WebAuth set REMOTE_USER, as do all other authentication plug-ins for Apache servers, so all code should use that environment variable wherever possible instead of any other.

Applications which rely on the environment variables set by older versions of WebAuth can turn on backwards compatibility, as described above.

The SU_AUTH_AGE environment variable, which gives information about the status and expiration time of the user's authentication credentials, has been replaced by three environment variables that all contain Unix timestamps (seconds since epoch): WEBAUTH_TOKEN_CREATION, WEBAUTH_TOKEN_EXPIRATION, and WEBAUTH_TOKEN_LASTUSED.

Further Documentation

Last modified Friday, 12-Dec-2014 02:31:11 PM

Stanford University Home Page