Skip navigation

STANFORD UNIVERSITY

INFORMATION TECHNOLOGY SERVICES

WebAuth Frequently Asked Questions

Table of Contents

Protocol and Functionality

Supported Platforms

Installation Problems

Protocol and Functionality

How do I log out of WebAuth v3?

WebAuth v3 single sign-on credentials are stored in the browser as a session cookie, as are all of the individual login credentials for each authenticated site a user has visited. In practice, this means that users of WebAuth v3 services need to exit their browsers to log out. This is inherent in the design and is due to the limitations of how cookies are handled by browsers.

It is possible to go to logout pages on every application that the user visited and then go to the logout page on weblogin to also destroy the single sign-on cookie, but this is generally far more effort than simply exiting the browser (and if any of those sites are missed, the user would continue to be authenticated to that site until the credentials timed out). Exiting the browser is far more reliable.

It is very important to stress to all WebAuth v3 users that if they log on to protected sites using a shared machine, they need to exit out of all of their browser windows and close the browser application when they're done in order to keep someone else from intentionally or inadvertantly using their credentials.

For kiosk users and other situations where the actions of the browser are limited, there needs to be some sort of reset mechanism that clears all session cookies and preferrably also the browser history. This is a good idea for kiosk browsers regardless, as many sites on the Internet besides WebAuth-protected sites use cookies as an authentication mechanism.

For previous users of Stanford's WebAuth v2.5, this seems to be a substantial change, but isn't as much of one as it may appear to be at first glance. The belief that logging out of PC Leland or MacLeland would destroy all of the user's authentication credentials was already in part erroneous. Any site that the user visited that used a cookie for an authenticated session would have still been available to anyone who came up to the system afterwards. WebAuth v3 increases the visibility of this situation, but does not fundamentally change it.

Unfortunately, there is no way to change this behavior and still preserve the most significant design goal for WebAuth v3, namely seamless operation through NAT and firewalls. This problem is inherent in a cookie-based security model. However, individual applications that need a higher level of security can impose additional restrictions on the freshness of the authentication credentials, or force a login even if the user already has a single sign-on cookie.

If you want to set up a logout page for your particular application, here are details on setting up a logout page.

Why does weblogin display another page after login?

If WebAuth is not configured to use another authentication type (such as SPNEGO), weblogin will prompt you for your username and password. Then, after authentication, weblogin will display an additional page confirming that you're logged in and providing a link to click on to continue to the web site you were trying to access.

Users frequently ask for this intermediate page to be eliminated, but it is required by the HTTP protocol. The return page of a POST (such as entering your username and password) may not be an immediate redirect to another page. This is the primary reason for the intermediate page, but since we had to present it anyway, we also use it to tell users they have been authenticated to a particular web site and would also tell users about any additional credentials that web site requested (if any). It's a final opportunity to abort logging in if the user decides they don't want to authenticate to that site.

This authentication page is always presented for consistency of the user interface. It would technically be possible to skip the intermediate page if and only if the user were already authenticated with a single sign-on cookie or some other non-interactive authentication mechanism were used, but then sometimes one would see this page before going to a protected site and sometimes one wouldn't. Users get used to always seeing this page over time and even appreciate the warning that they're now visiting a restricted site.

Why do cookies not work for unqualified hostnames?

There is no notion in HTTP of multiple names mapping to the same host and being treated as equivalent. From the perspective of both your browser and the Apache server, https://<host>/ and https://<host>.stanford.edu/ are two completely different sites. That's why you get a certificate warning for the former due to the certificate mismatch.

WebAuth, like nearly all cookie-based web authentication systems, uses scoped cookies to store authentication credentials. Scoped cookies are restricted to the specific hostname of the URL you were visiting when the cookie is set. Therefore, the cookie set for the host <host> is not presented by your browser to <host>.stanford.edu. From the browser perspective, they're two different hosts.

If you want all users accessing <host> to actually go to <host>.stanford.edu, the best way of handling this is through explicit configuration telling Apache that. For example, instead of having:

    <VirtualHost *:80>
        ServerName example.stanford.edu
        ServerAlias example

        # ...
    </VirtualHost>

do:

    <VirtualHost *:80>
        ServerName example.stanford.edu

        # ...
    </VirtualHost>

    <VirtualHost *:80>
        ServerName example
        Redirect / http://example.stanford.edu/
    </VirtualHost>

That way, all clients accessing the short name will be redirected to the proper name in advance of any authentication or cookie setting.

Why does WebAuth not work for subdomains of hosts?

If you have a web server named service.example.com and you bring up a new version as beta.service.example.com, you will quickly discover that some clients (specifically those using IE 7 and perhaps other browsers) will not be able to authenticate correctly if they have tried to log on to both sites.

The problem here is a bug in the cookie handling in IE 7. The HTTP cookie protocol says that cookies that are not explicitly domain-scoped should only be sent to hosts that exactly match the host specified in the cookie. Unfortunately, IE 7 does not correctly implement this requirement and will instead send both the service.example.com and the beta.service.example.com cookies to beta.service.example.com. The second WebAuth authentication cookie (the one for service.example.com) is often sent first, and the WebAuth server finds it, can't decrypt it (since it uses a different key), and rejects the client's authentication.

Working around this IE 7 bug will require a change to the server code to check multiple cookies if multiple cookies were received. This work hasn't been done yet. In the meantime, if you have IE 7 clients, the best approach is to not set up this sort of hierarchy in DNS if you can avoid it. Use service-beta.example.com instead of beta.service.example.com, for example.

Supported Platforms

What platforms does WebAuth support?

The primary target platform for WebAuth development is Linux, but the code should be portable to any Unix system. The modules make extensive use of Apache's APR libraries for portability. It has been successfully built on Solaris 8 and later and on Mac OS X 10.2 and later (with a locally built OpenSSL for earlier versions of Mac OS X). WebAuth should also build on AIX, including the LDAP module once Cyrus SASL has been ported to that system, but this has not been tested for some time.

The primary portability constraint is likely the support libraries that WebAuth needs. For basic authentication, only OpenSSL, cURL, and MIT Kerberos or Heimdal are required, which are all very portable. The LDAP lookup code, however, requires OpenLDAP and Cyrus SASL, and the latter may be difficult to get working on unusual platforms (particularly platforms with unusual shared library handling).

If you have ported WebAuth to a new platform and had to make code changes to get it to compile, we would be very interested in the changes needed. Please post your patches to the webauth-info mailing list.

Can WebAuth run on Windows?

A port to Apache for Windows was present in the WebAuth 3.2.0 release, but was not maintained and has since been dropped. We cannot currently support this port or help with installation, but it may be a useful starting point for further work.

An initial implementation as an IIS filter was completed, but it had various problems that made it unsuitable for general use. A good Windows implementation requires an IIS extension to create a security context. Further work on this is currently stalled, but if you are interested in working on it, please contact us.

How do I build WebAuth on Mac OS X?

With Developer Tools installed, you should have everything that you need to build and run WebAuth. There are only a few caveats:

The MACOSX_DEPLOYMENT_TARGET variable needs to be set to 10.8 or some other appropriate version:

    export MACOSX_DEPLOYMENT_TARGET=10.8

You can then configure WebAuth with:

    ./configure --with-apxs=/usr/sbin/apxs

and continue according to the regular installation instructions.

You will also need to ensure that Kerberos is configured. Stanford users who have installed Stanford Desktop Tools on that system should already have the appropriate Kerberos configuration. Otherwise, obtain the krb5.conf file for your site and install it in /Library/Preferences/edu.mit.Kerberos.

If you are doing this at Stanford, note that you will need to either build remctl and wallet for Mac OS X, or run wallet on a Linux cluster system like a cardinal in order to get a keytab and then scp it down to your Mac OS X system.

For very old versions, such as 10.2, Mac OS X doesn't come with sufficiently current libraries or with Apache 2.x. On an older version of Mac OS X, you will need to install Apache 2.x, cURL (if using a version older than 10.3), and the most recent version of OpenSSL (you need 0.9.7 or later) built shared and with threads. Then, configure WebAuth as above but possibly with a different --with-apxs option and additional --with-apr, --with-aprutil, --with-curl, and --with-openssl options to reflect the different installation paths. For LDAP support, you will also need to build and install local versions of Cyrus SASL and OpenLDAP. None of this should be needed with 10.4 and above.

How do I fix generic error from KDC 20 on Mac OS X?

If you get the following error in your log files when using Mac OS X:

mod_webauth: krb5_webkdc_credential: webauth_krb5_new failed: Kerberos error (Generic error from KDC 20)

it may be because the user and group that Apache is running as are invalid. Apache by default tries to run with user nobody and group #-1, but for some reason those settings appear to cause the above error on Mac OS X.

Changing the user and group in your httpd.conf to www and www appears to solve the problem.

How do I build WebAuth on Linux?

If you're using Debian or Ubuntu, you probably don't have to. Packages for Debian and Ubuntu are available, both from the Debian unstable and Ubuntu breezy (and later) archives and from a separate archive for sarge packages. Otherwise, read on.

WebAuth should build on Linux as on any other Unix, but there are a few things to be aware of when doing so.

First, most Linux distributions come with the libraries required by WebAuth and many come with an Apache 2.x installation, but they may not be the right versions. Check the version requirements of WebAuth against the installed versions of those packages and make sure that they're new enough. If not, you may need to download a later version and install it yourself in /usr/local and then point the WebAuth configure script there. In particular, make sure OpenSSL is at least 0.9.7 and Apache is at least 2.0.43 (2.0.54 is recommended due to security fixes). If the installed version is suitable, make sure that you have the development packages installed as well as the library packages so that you can compile against the libraries.

A suitable Kerberos library is probably available, but on Red Hat, Kerberos may be installed in /usr/kerberos rather than into the normal paths.

Be particularly careful of the OpenLDAP libraries. WebAuth requires a version of OpenLDAP that supports GSSAPI authentication and Kerberos. Some Linux distributions ship with a version of OpenLDAP suitable for WebAuth, but without GSSAPI support. Others provide suitable OpenLDAP and Cyrus SASL packages, but don't install the Cyrus SASL GSSAPI support by default (it's a separate package that must also be installed). Again, if you can't find the right packages from your Linux distribution vendor, you may need to download the latest source and install the packages yourself in /usr/local.

In general, you want to try to use as many of the system libraries as possible, and if you build WebAuth against libraries you installed in /usr/local, you must make sure that Apache and all modules it loads use the same libraries. See the information about segfault problems for more information.

Installation Problems

WebAuth causes Apache to segfault

Almost all segfault problems involving WebAuth are caused by shared library conflicts. In order to understand what causes them and how to fix them, some background on shared libraries and Apache modules is required.

When Apache loads a module that's linked against other shared libraries, it loads all of those shared libraries into memory as well, if they aren't already. So long as all of its modules use the same versions of any shared libraries they have in common, everything is fine. If, however, two modules load different versions of the same shared library (or two shared libraries providing the same symbols), even through their dependencies, Apache will probably segfault. It might segfault right away, or it might not segfault until one of the affected functions is called.

To see what shared libraries a particular module loads, you can run:

    ldd /path/to/module.so

On at least most ELF platforms, this will show you the complete set of libraries that the module pulls in, including ones pulled in as dependencies of the shared libraries that it loads. You can use this to check for library conflicts.

The most frequent conflict is with the OpenLDAP libraries. mod_webauthldap has specific requirements for OpenLDAP, which often leads people to install new OpenLDAP libraries in /usr/local. However, other Apache modules may be linked against the system OpenLDAP libraries (mod_php is a common offender). When both libraries are loaded at the same time, chaos ensues. The best solution is to link everything against the same OpenLDAP libraries (which may require rebuilding mod_php against your newer OpenLDAP libraries if the system version is too old) and removing all other copies of the OpenLDAP libraries from the system if possible.

The other common problem is with Kerberos libraries. mod_webauth (via libwebauth) and mod_webauthldap (directly) both link against a Kerberos library. OpenLDAP doesn't link against Kerberos directly, but it does link against Cyrus SASL and uses the GSSAPI authentication mechanism, which means that as soon as mod_webauthldap tries to authenticate to your directory server, Cyrus SASL will also load a Kerberos library. Again, if Cyrus SASL is linked against the system Kerberos libraries, but one of the other modules is linked against a separate Kerberos installation, chaos and segfaults will ensue.

The best solution to this problem, when possible, is to always use the libraries that ship with your system if available. As long as the LDAP libraries are at least 2.1, WebAuth's needs are fairly modest and it doesn't really need the latest and greatest. The other software that you use will probably be linked against the system libraries, so this is the simplest way of avoiding conflicts.

If that isn't possible, you can take one of two routes. Either you can try to replace as few libraries as possible and then make sure that you've rebuilt every Apache module you use that depends on those libraries, or you can rebuild everything against your library set (usually including Apache itself). Both work, although if you take the latter approach, make sure to set LD_RUNPATH (or the equivalent on your platform) when building all the software to point to your new library installation (usually /usr/local/lib). Otherwise, when you run Apache, it may still find the system libraries first.

Here are some additional notes on shared library search paths for more information.

Why can't the server get a service token?

If the module loads properly (as indicated by the status messages in the server error log) but then can't obtain a service token from the WebKDC and can't display any authenticated web pages, the most likely cause is a permissions problem. Check your installation against the installation instructions, paying careful attention to the conf/webauth directory. This directory must be writable by the user that the child web servers run as (the User and Group directives in your httpd.conf file). It must also contain the WebAuth keytab file, and that file must also be readable by the child web servers.

If you're getting an error message that contains something like: "Kerberos error (Cannot resolve network address for KDC in requested realm)", the problem is likely that your krb5.conf file does not contain information for your local realm. Stanford users should get a copy of this file from /usr/pubsw/etc/krb5.conf and replace /etc/krb5.conf with that. This is generally only a problem for Linux users who are using the Kerberos version that comes with their distribution.

If you're having difficulty debugging the problem, try uncommenting this section in the WebAuth configuration:

    <Location /webauth-status>
        SetHandler webauth
        Order allow,deny
        Allow from all
    </Location>

and restart your server. Then go to the /webauth-status URL on your server and see what it says. It will perform various permission checks on your configuration.

I just get authentication errors. Help?

Be sure that you're connecting via SSL (https://), not with unencrypted HTTP (http://). WebAuth requires SSL to protect the user's credentials. If you want the server to automatically redirect users to the SSL version of the page, see the WebAuthSSLRedirect configuration option.

If you get connection refused errors when using SSL, make sure that your Apache server is configured to use SSL. If using the default startup scripts, you need to run apachectl startssl rather than just apachectl start to enable SSL.

How do I configure a logout page?

First off, please read about WebAuth v3 and logout. The best way for a user to log out after having authenticated to a WebAuth v3 web page is to close their browser, thus destroying all of their session cookies.

That being said, if you want to provide a logout page for your particular application, here's how to configure it. First, determine what location in your web site (suitable for an Apache <Location> directive) will be your logout page. Add a section like the following:

    <Location /logout.html>
        WebAuthDoLogout on
    </Location>

to your Apache configuration and restart your server. Now put your logout page in the right place to be served out as /logout.html or whatever URL you chose.

Please include on this page the recommendation that the user close their browser in order to log out of all WebAuth-protected web sites and warn the user that unless they do so, another user could still access applications as them without needing their password. Please also include a link to <https://weblogin.stanford.edu/logout> (at Stanford; other sites will have some equivalent URL) so that the user can destroy their single sign-on credentials. Unless they do this, a subsequent attempt to access your site will succeed without requiring a password unless you've disabled single sign-on for your site or their credentials have expired.

How do I fix random number failures?

If the test suite complains about "Assertion failed: s==1, file random.c" or you get failures involving random number creation, this means that OpenSSL has been unable to find a suitable source of randomness. On Linux and current versions of Solaris, OpenSSL will just use /dev/random, but other operating systems may not have that.

OpenSSL tries to find a good source of randomness both at compile time and at run-time. There are a variety of ways to provide it with a good source of random numbers, but probably the easiest is to install either PRNGD or EGD (a Google search should return source locations) and have it generate an entropy pool in /var/run/egd-pool, which OpenSSL knows to look for by default.

"Too many open files" error from mod_webauthldap

mod_webauthldap uses a keytab to obtain Kerberos tickets, which it uses to authenticate to an LDAP directory. The keytab handling inside the MIT Kerberos libraries uses stdio. This means that, on platforms that have limitations in the maximum file descriptor number that can be used with stdio, you may see "too many open files" errors when mod_webauthldap attempts to obtain tickets.

This is most frequently a problem on Solaris, where stdio is limited to 256 file descriptors on 32-bit systems.

The easiest fix for this problem is normally to reduce the number of file descriptors that Apache is keeping open. One common cause of too many open file descriptors is duplicated Apache *Log directives. If you put *Log directives in each of your virtual hosts, Apache will open separate file descriptors for each log in each virtual host. If all virtual hosts are logging to the same log files, move the *Log directives outside of the virtual host blocks and you'll immediately significantly reduce the number of open file desciptors.

For a complete description of this problem and other possible solutions, see the Sun Developer Network article on the topic.

Last modified Tuesday, 21-May-2013 09:49:04 AM

Stanford University Home Page