About the Central Authentication Hub

The Central Authentication Hub (CAH), also known as "Internet Login", is a web-based single-signon system providing centralized authentication services for applications at the University of Minnesota. Its API is completely based on standard web redirects, and is thus completely platform and language agnostic. It is similar to (and in some cases was the model for) other WebSSO systems such as JA-SIG's CAS or Pubcookie (originally from the University of Washington).

CAH was first prototyped in January 1998, and the first functional version went live in September of that year. The first version used public-key cryptography to digitally "sign" a cookie that could then be validated by the application. The first application to use CAH was the Whistler project, in support of web-based class registration. In February 1999, support was added for the more secure Enterprise password, and the public-key cookie was replaced with a more robust and secure symmetric-encrypted cookie (hence the "v2" at the end of the umnAuth cookie name).

Contents

How it works

Overview diagram of CAH

Here is a description of the flow of events during a typical visit to a website protected with CAH. First, the end user attempts to access a protected resource on a web server (diagram step 1). The web server looks for the presence of the authentication token, a cookie named umnAuthV2. If it is not present, the web server sends the browser a redirect to the login service (diagram step 2). See below for details on the possible parameters.

The CAH login service authenticates the user using one of several possible methods (diagram step 3). The user stays at the login service site until authentication is successfully completed. The login service validates the user's credentials (diagram step 4), and once verified redirects the user to the callback URL specified by the protected web server (diagram step 5). Normally, this is the same URL the user originally requested, but it is not required that this be so.

Now the user's browser follows the redirect to the protected web server (diagram step 6). This time, the web server will see the authentication token and knows to proceed. First, it should see if it has cached validation data for the cookie; if present, the cache data should be used to avoid a call to the validation service, and the web server should proceed to the access decision step. If not, the application connects to the validation service to extract and verify the authentication token data (diagram step 7; this is described in detail later). The validation service identifies the user, looking up additional information from the X.500 directory as appropriate (diagram step 8), and returns a success or failure code to the protected web server. If successful, it returns the authentication information, including validation level (determined by the strength of authentication that was used), Internet ID of the authenticated user, the time that the token was issued, and the IP address of the browser (diagram step 9).

The web server must then make a decision to grant or deny access to the resource based on the (possibly cached) data returned from the validation service. The validation level should be compared against the minimum level needed to access the protected content. The IP address from the token should be compared against the IP address of the request (see below for exceptions). The timestamp should be compared against the current time to see if it is too old. Note that the validation service will return failure for tokens older than 3 hours, so an application checking cached validation data should at least enforce this maximum. The Internet ID can be checked against a list maintained by the application to further constrain access if desired (but see below before deciding to use Internet ID as a long-term identifier).

If any of the above checks fail, the web server should send the browser a redirect to the login service with the appropriate error message parameter specified. Otherwise, the web server should serve the requested resource (diagram step 10).

There are a variety of ways to implement CAH protection. The sample Apache module is intended to be a drop-in replacement for Apache's mod_auth modules. You use configuration directives in httpd.conf or .htaccess files to apply CAH protection to a location, directory, or file, and the module will handle all the CAH processing for you. The REMOTE_USER environment variable is populated with the user's Internet ID. The module is intended to protect static files (HTML, images, PDFs, etc.) and scripts (CGI, PHP, etc.), and can also be used with mod_jk to protect servlets running on Tomcat or another engine.

Another common way to implement CAH is to program the interactions directly into an application script or servlet. More advanced web applications tend to use this technique to allow for more flexibility, for it allows the application to use alternate validation modules that return more information about the authenticated user. For example, many applications want the user's EmplID to use as a key to access more information about a user in Peoplesoft. Access to additional data requires that the owners of the data sign off on the request. OIT Data Security acts as a clearinghouse for these signoffs. The Access Request Form is used to request a module that returns additional data.

API details

Login service

A protected web server requests the login service by sending a redirect to the user's browser. The format of the redirect URL is: https://www.umn.edu/login?param1=foo&param2=bar&...&paramN=baz While none of the parameters are technically required, the use of at least "desturl" is highly recommended; otherwise, the user may have trouble getting back to your site!

Parameters

These are the supported parameters for the login service. There are also a few parameters for internal use by CAH itself that are not documented here. The internal parameters should not be referenced outside of CAH itself and may change at any time without warning.

desturl
Contains the "destination" URL which the login service will redirect the user's browser to after authentication is completed successfully. If this parameter is not specified, the login service will send the user a generic "you've authenticated OK" page, but it will not be able to link the user to the originating location. TODO: Someday, this may be changed to default to the referring page.
msg_idx
If set, the login dialog will display a message in red above the username/password form. The value of msg_idx determines which message will be displayed:
msg_idxDisplayed text
1Authentication timed out, please reauthenticate.
2IP mismatch.
3Stronger auth level required (account init, Internet password, Enterprise password, or PKI)
4Stronger auth level required (Internet password, Enterprise password, or PKI)
5Stronger auth level required (Enterprise password or PKI)
6Stronger auth level required (PKI)
7You are not in the list of allowed users of this site.
autocontinue
If set to 1, after successful authentication the main window will be refocused, leaving the small logout window in the background. Its use is discouraged since we would like users to actually read the logout window at least once. Also, newer versions of Mozilla Firefox disable the Javascript used to implement this by default.
no_popup
If set to 1, disables the small logout window from being displayed at all. This is to support certain embedded-browser applications like Breeze Live that do not share cookies across popped-up windows (so the popup would always show a nasty error message). Its use is highly discouraged.
enterprise
A protected web server can set this value to 1 to indicate that the requested resource requires the Enterprise password level of authentication. If set to 1, the login service changes the login dialog text to reflect that an Enterprise password is required. In the future, a more generalized parameter will be introduced to allow the application to specify exactly the minimum level of authentication desired, and the CAH login will adjust accordingly. enterprise will be kept for backwards compatibility.
do
This parameter has several values, of which only one may be invoked by protected web servers. If the value of do is refocus, the login service will emit Javascript to bring the small logout window back to the foreground, then immediately redirect the main browser window to the location specified by the desturl parameter. As with autocontinue, newer versions of Mozilla Firefox by default disable the Javascript used to implement this feature. This is one way an application can perform a single-signon-friendly "logout". See below for another method.
guestable
This parameter can take a variety of values, each of which causes the login dialog to change slightly to indicate that a guest account may be used with this site. In particular, it makes the "create a guest account" button appear on the login form. Whether or not a guest login will actually work does not depend on the value of this parameter, but rather on the validation modules called to verify the cookie. Valid values for this parameter are:
guestableFunction
1Standard guest accounts
2Admissions guest accounts
3Portal guest accounts
4Twin Cities Alumni Association precreated accounts
5Duluth Alumni Association precreated acounts

Logout service

To request the logout service, a protected web server should link to or send a redirect to a URL of this form: https://www.umn.edu/logout?param1=foo&param2=bar&...&paramN=baz At this time, only the desturl parameter is defined. Its function is similar to its counterpart in the login service: if defined, after successfully logging the user out, the logout service will send a redirect to the browser back to the value of desturl. If it is omitted, a generic "you have logged out" message will be displayed to the end user.

Whether to use this feature or not requires a bit of thought, as it is a tradeoff between increased security (by making it easier for the user to get logged out) versus single-signon functionality (just because a user is finished using your application doesn't necessarily mean they want to be logged out from other applications they may be using).

Validation service

The web server uses the validation service to validate that a user's cookie is valid and to extract authentication information from the cookie and/or X.500 directory. The validation service understands multiple protocols for access; a web server can use any one of them to perform the validation.

TCP/SSL connection

To use this method, open a TCP/SSL connection to host x500.umn.edu port 87. Then send: MODULENAME<tab>param1value<tab>param2value<tab>...<tab>paramNvalue<cr and/or lf> Most CAH modules (including the standard WEBCOOKIE module accessible to any application; see section XXX for more information on available modules) take a single parameter, the cookie value. If the validation fails (due to a syntax error, no access to the module, or an expired cookie), the response from the server will be: NO:University of Minnesota, US If validation succeeds, the response will vary depending on the module that was requested. The standard WEBCOOKIE module responds with: OK:30|1234567890|127.0.0.1|cab| The fields (after the OK: prefix) are vertical-bar-delimited and are (in order): validation level, timestamp (in UNIX format, i.e. number of non-leap seconds since Jan 1, 1970 00:00 UTC), IP address (decimal dotted quad format), Internet ID, and blank (was the X.500 Distinguished Name in version 1, but is no longer populated and should be ignored).

Current validation levels are:

LevelAuthentication method
5Forced password change - protected web servers must NOT allow access at this level
10Guest account
15Guest account - vouched for by a UMN staff member
20User initiated their account for the first time
30Internet password
40Enterprise password
50Two-factor

Most protected resources will require level 20 or higher; enterprise applications, 40 or higher.

HTTPS connection

Make a request to: https://x500.umn.edu:87/MODULENAME?param1=foo&param2=bar&...&paramN=baz The names of the parameters can be just about anything. To map from named parameters to the positional parameters used internally by the validation modules, the parameter names are sorted (in ASCII order).

The response will come in the body of the HTTP response; it is formatted the same as the TCP/SSL connection method responses. The HTTP status code should always be 200 OK regardless of the success or failure of the request.

There is also a deprecated HTTPS syntax using "pathinfo" to pass parameters, but some client implementations cannot handle the necessary escaping of slashes that occasionally appear in cookie values, causing intermittent to frequent failures. The GET parameter form above should be used instead.

Web Services connection

A Web Services connection method is planned; any application developer who wishes to use it should contact Internet Services.

Cookies

After a successful authentication, the login service sets a couple of cookies in the browser that the protected web server uses to validate the authentication. Both of these cookies are scoped to umn.edu and are marked secure, so web servers that want to make use of them must have a domain name ending in umn.edu and use HTTPS. In particular, this means that you need a working DNS name for your server; using an IP address will not work.

The most important one is umnAuthV2. This contains the authentication token, which is an opaque, encrypted blob of URL-encoded data that is only readable by the CAH validation service. The protected web server must decode the URL encoding before passing the cookie value to the validation service.

The other cookie is umnAuthReferrer. This contains the Referrer header the browser sent to the login service upon first contact. A site that uses a generic desturl could conceivably use this header to dispatch returning users to the place they left, but this is strongly discouraged because (1) the user may be using a privacy protection program or have a browser that doesn't send Referrer headers, and (2) it contains the Referrer header from the time of authentication, and since CAH is a single-signon service, it may not even be your site! Since the latter is a potential privacy concern, this header may be eliminated in future versions of CAH and should not be used in new implementations, but it is documented here for completeness.

Test Instances of Services

Both the login and validation services have corresponding test instances that can be used by changing the hostname you contact; use www-test.umn.edu instead of www.umn.edu and x500-test.umn.edu instead of x500.umn.edu. We strongly recommend that you use the test instances during application load testing to minimize the impact on production CAH services. The test services operate against the test instance of the X.500 directory, which may not always be up-to-date with respect to the production X.500 directory, so be aware that some data (and passwords) may be older than you would expect.

User masquerading

To facilitate developer testing of CAH-protected applications, there is a mechanism where a user can spoof a login of another user. To do this, the developer enters the word test as the username in the standard CAH login dialog box, and leaves the password blank. This will bring up a new login dialog that allows the developer to authenticate and specify the Internet ID and validation level they wish to spoof. The cookie that is set is marked as a spoofed cookie, and can only be validated if the protected web server changes the TCP port for validation from 87 to 8700. Thus, web servers not specifically configured to accept spoofed cookies will reject them, thus helping protect production systems against rogue developers.

In order to use this feature, your Internet ID must be registered with OIT Data Security.

Masquerading can be used with either the production or test instance of the CAH services. This has caused some confusion, because when this feature was originally introduced it was known as "developer test login", which is easily confused with the test instance of CAH services. Adjusting the terminology to "masquerading" or "spoofing" is intended to reduce or eliminate the confusion.

Also, it is possible to use the word prod instead of test to force the developer's authentication to use the production X.500 directory when accessing www-test.umn.edu. This allows for testing with users in the test instance of the X.500 directory when the developer is not present there.

Validation Modules

A protected web server can send any of a number of module names (also known as "verbs" or "application identifiers") to the validation server.

Module nameBehavior
WEBCOOKIEStandard request
WEBCOOKIEGsame as WEBCOOKIE, but allows guest accounts to be used; usually used with "guestable=1" parameter to the login service
WEBCOOKIE_STAFFsame as WEBCOOKIE but only allows users who are "staff"
WEBCOOKIE_STUDENTsame as WEBCOOKIE but only allows users who are "students"
WEBCOOKIE_STUSTAFFsame as WEBCOOKIE but only allows users who are "student" or "staff"

Implementation requirements (Do's and Don'ts)

DO check for the presence and validity of the authentication token on EVERY request; the absence of this token indicates a logout has taken place.

DO keep a cache of cookie values and the data returned from the validation service. Since you need to check the cookie value on every request, you don't want to hammer the validation service repeatedly during the course of a session. If you have an application that keeps session state, it is OK to keep the cookie value and data from the validation server in the session state, but be sure to check on every request that the browser cookie is still present and that the value matches the one in the session state.

DON'T assume that a user requesting the "starting point" of your application is not yet authenticated -- CAH is a single-signon system. DO check existing cookies for validity as usual, of course.

DO compare the IP address returned by the validation service against the IP address of the user's browser. If your web server is behind a load balancer, it may not be possible to get the browser's IP address, in which case you will have to forego this check (and thus increase your protected server's vulnerability to cookie stealing). Some load balancers can be configured to insert an HTTP header that gives the true client IP address. DO use this feature to check the cookie IP if possible.

DON'T rely on the Internet ID as a long-term primary key. Faculty and staff can request a change at any time, and users often change their Internet ID if their name changes (e.g. getting married). There is a Directory Identifier (umnDID) that is better for this purpose. For now, ask for details if interested. Short-term use of Internet ID as a key is just fine.


Christopher A. Bongaarts

Last modified: Fri Feb 6 08:58:03 CST 2009