About the Central Authentication Hub
The Central Authentication Hub (CAH), also known as "Internet Login", was a web-based single-signon system providing centralized authentication services for applications at the University of Minnesota. Its API was completely based on standard web redirects, and was thus completely platform and language agnostic. It was 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).
This document describes the CAH service and how to develop applications to use it. The Login service has been or is about to be retired (as of May 2016), as Shibboleth is now the preferred Web SSO system at the University. The Validation service, however, is still used by some applications, especially those that need access to U Card photos, where a user cookie is not used. The primary purpose of this document at this point is to document the Validation service for those applications.
- How it works
- API details
- Login service
- Logout service
- Validation service
- TCP/SSL connection
- HTTPS connection
- Test Instances of Services
- User masquerading
- Validation Modules
- Login service
- Implementation requirements (Do's and Don'ts)
How it works
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
.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_proxy_ajp 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 Provisioning and Requests 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:
https://www.umn.edu/login?param1=foo¶m2=bar&...¶mN=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!
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.
- 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.
- If set, the login dialog will display a message in red above the username/password form. The value of
msg_idxdetermines which message will be displayed:
Displayed text 1 Authentication timed out, please reauthenticate. 2 IP mismatch. 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.
- 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.
- 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.
enterprisewill be kept for backwards compatibility.
- This parameter has several values, of which only one may be invoked by protected web servers. If the value of
desturlparameter. As with
- 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:
Function 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:
https://www.umn.edu/logout?param1=foo¶m2=bar&...¶mN=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).
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:
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:
|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:
https://x500.umn.edu:87/MODULENAME?param1=foo¶m2=bar&...¶mN=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.
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
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. Contact Identity Management if you would like to have users populated in the test directory from production for testing.
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.
A protected web server can send any of a number of module names (also known as "verbs" or "application identifiers") to the validation server.
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.