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).
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
mod_auth modules. You use configuration
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.
A protected web server requests the login service by sending a
redirect to the user's browser. The format of the redirect URL is:
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!
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.
msg_idxdetermines which message will be displayed:
|1||Authentication timed out, please reauthenticate.|
|3||Stronger auth level required (account init, Internet password, Enterprise password, or PKI)|
|4||Stronger auth level required (Internet password, Enterprise password, or PKI)|
|5||Stronger auth level required (Enterprise password or PKI)|
|6||Stronger auth level required (PKI)|
|7||You are not in the list of allowed users of this site.|
enterprisewill be kept for backwards compatibility.
desturlparameter. As with
|1||Standard guest accounts|
|2||Admissions guest accounts|
|3||Portal guest accounts|
|4||Twin Cities Alumni Association precreated accounts|
|5||Duluth Alumni Association precreated acounts|
To request the logout service, a protected web server should link to
or send a redirect to a URL of this form:
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).
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.
To use this method, open a TCP/SSL connection to host x500.umn.edu
port 87. Then send:
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:
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
Current validation levels are:
|5||Forced password change - protected web servers must NOT allow access at this level|
|15||Guest account - vouched for by a UMN staff member|
|20||User initiated their account for the first time|
Most protected resources will require level 20 or higher; enterprise applications, 40 or higher.
Make a request to:
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.
A Web Services connection method is planned; any application developer who wishes to use it should contact Internet Services.
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
umn.edu and use HTTPS. In particular, this means that
you need a working DNS name for your server; using an IP address will
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
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
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
x500-test.umn.edu instead of
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.
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
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
A protected web server can send any of a number of module names (also known as "verbs" or "application identifiers") to the validation server.
|same as |
|same as |
|same as |
|same as |
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.
Last modified: Fri Feb 6 08:58:03 CST 2009