UMBC’s WebAuth
Introduction
WebAuth is the web services “single-sign-on” system in use at UMBC. It has a logical structure similar to that of Kerberos, in that users are issued a “ticket granting cookie”, which is then used to authorize the issuance of “service cookies” for requesting applications. WebAuth consists of two components. The first, a server component, which handles the user’s interactions with the system (a login screen and some utilities), and the issuance of the cookies referenced above. The second is the client component, which currently exists in Perl 5.x & Java implementations. The Perl implementation has three levels of functionality; as component to a script using the popular CGI.pm module, as a component in a mod_perl application, and, if mod_perl is available, as a server-level provider of authentication.
WebAuth is written and maintained by Robert Banz (banz@umbc.edu, http://www.membrain.com). The Java client code was written by Brian Cuthie. WebAuth is available under a BSD-style license from http://www.umbc.edu/oit/syssw, along with other useful “middleware.”
Functional Specification
WebAuth utilizes HTTP redirects to do its magic. There are two standard use cases – one, where a user has logged into the system and has a valid “ticket granting cookie”, and the second, where the user has not received a ticket granting cookie yet (or the cookie has expired), and is required to authenticate themselves. For the sake of doing things in order, the second will be considered first.
Usage Case: Un-Logged-In User
Step 1
The user makes a request of an application. The application requires authentication, but does not detect that the user’s browser contains a valid “Service Cookie”.
Step 2
The application returns a redirect to the user’s browser, consisting of the URL to the WebAuth server, and information regarding the specific type of the authentication needed (usually, simply the name of the requesting sevice).
Step 3
The user’s browser presents the redirected URL to the WebAuth server. The WebAuth server detects that the user does not currently have a valid “Ticket Granting Cookie” available, and presents the WebAuth login screen.
Step 4
The user responds (correctly, of course) to the login query. The login server replies by creating a “Ticket Granting Cookie”, and a redirect back to the requesting web application. A CGI variable is set which will be understood by the WebAuth client software, containing information to be set in a cookie that is only readable by the particular web server the application is running on.
Step 5
The user’s browser presents the URL to the application server. The application server sets the cookie that was requested, and will “accept” this cookie as appropriate authentication for the lifetime of the cookie.
Usage Case: Logged-In User
Step 1
The user makes a request of an application. The application requires authentication, but does not detect that the user’s browser contains a valid “Service Cookie”.
Step 2
The application returns a redirect to the user’s browser, consisting of the URL to the WebAuth server, and information regarding the specific type of the authentication needed (usually, simply the name of the requesting sevice).
Step 3
The user’s browser presents the redirected URL to the WebAuth server. The WebAuth server detects that the user has a valid “Ticket Granting Cookie”.
Step 4
The user’s browser is redirected back to the requesting web application. A CGI variable is set which will be understood by the WebAuth client software, containing information to be set in a cookie that is only readable by the particular web server the application is running on.
Step 5
The user’s browser presents the URL to the application server. The application server sets the cookie that was requested, and will “accept” this cookie as appropriate authentication for the lifetime of the cookie.
Trivial, and Degenerate Usage Cases
These fall into two categories. One, the user does present a valid “Service Cookie”, which is accepted by the user’s application (through the WebAuth client software). The second, is when the user is redirected to the WebAuth server, and does not appropriately authenticate themselves. In this case, the user is not able to log in, and does not get redirected back to the requesting application.
The Service Cookie
The service cookie is a 3DES encrypted, and Base64 encoded string. The string consists of “useful information” such as the users’ principal, ticket expiration time, and how the user was authenticated – and, and MD5 hash of this data for verification. The encryption key, like in the Kerberos model, is a “shared secret”, known only to the WebAuth server and the application requesting the authentication. The “lifetime” of the cookie is requested by the application, and defaults to “something reasonable”, such as an hour.
The “Ticket Granting” Cookie
The ticket granting cookie is, for all intents and purposes, a service cookie, with the service name “TGS”. It usually has a lifetime longer than a service cookie, as it is expected service cookies may be reissued many times during a session – but the wish to pester the user for authentication information multiple times during a session may be undesirable. UMBC currently leaves the expiration time of the “Ticket Granting” cookie set to 12 hours.
WebAuth’s Evolution
The functionality described above is true for the current version of WebAuth. However, the initial implementation of WebAuth required the use of “domain-wide” service cookies, as they were set by the WebAuth server itself. Current WebAuth clients request the use of their “Remote Cookie Setting Service”, as in the usage cases above – however, the old behaviour is still supported for backwards compatibility with clients which have not yet been upgraded.
Creating A WebAuth Server
WebAuth requires the following:
- An Apache 1.x Web Server, with
- mod_perl
- SSL-enabled (this is HIGHLY recommended. If you don’t agree, you shouldn’t be reading this.)
- …and the following Perl modules:
- CGI
- CGI::Cookie
- CGI::FastTemplate[1]
- Mime::Base64
- MD5
- LWP::Simple
- MIME::Base64
- Crypt::TripleDES
- …and, if using the supplied Password.pm (which you probably won’t)
- UMBC::LDAP::PersonUtil
- Mozilla::LDAP::Conn
(these perl modules, all of course,
have 300 kazillion dependencies of their own. Have fun.)
The following code should be in your httpd.conf:
All of the parameters named by PerlSetVar are configurable.
Here’s what they mean:
|
ServerKeyDatabase |
Location of the database (a DBM file) where the server’s shared secrets are stored. |
|
CookiePrefix |
The prefix given to all of the cookies created by WebAuth |
|
KeyExpiration |
The default expiration time, in minutes for a service ticket. |
|
KeyDomain |
For backwards compatibility, the large “cookie domain” used for downrev clients. |
|
TGTExpiration |
The time, in minutes, a Ticket Granting Cookie can live. |
You must also create at least one secret which is used by the “Ticket Granting Cookie”. This can be done with the script “AuthKey.pl” which is included in the distribution.
Be sure to edit the script and have it update the correct DBM secret file that
you have called out above.
Setting Up an Authentication Module
WebAuth includes a “pluggable” authentication module system. In our environment, users who do not yet have a username may log in via their “Student ID Number” and “PIN” (which are provided by the registrar), allowing them to then register for an account. Most of our applications only accept the authentications given by included “Password” module, except, as you may guess, the account creation system, which will accept an authentication type “SSNPin”. The Password.pm module that is provided (under the AuthType directory) is the most advanced that we use – as it provides for users identifying themselves multiple ways, and also implements the “ticket augmentation” functionality, which is used to add information to a ticket as configured, on an application-by-application basis.[2] The latter could potentially be expanded to “remove” authentication information from a ticket, and replace it with authorization information, such as that provided by the Shibboleth system (http://www.internet2.edu/middleware/shibboleth), but, by the time that happens, we’ll all be using Shibboleth, and system such as this will be relegated to the ranks of things like DOS. It is doubtful that you will find the provided Password.pm module to be to your liking, as it is specific to our middleware infrastructure – however, it does everything that it theoretically can.
Setting Up a Client Application
This documentation has moved to https://spaces.umbc.edu/display/CIG/WebAuth+Perl+API.