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
cardinal.stanford.edu 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/system.stanford.edu. 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.
S/Ident
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 weblogin.stanford.edu, 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
- WebAuth v3 documentation
- Installation instructions
- mod_webauth reference manual
- mod_webauthldap reference manual
