Pubcookie provides single sign-on authentication to web sites using existing site-wide authentication services. In this way, a user who has already authenticated for access to one web site can access other protected sites without having to enter another password. For example, a user who has authenticated to a webmail system could browse a separate web database system without needing to login again.

Pubcookie provides the glue between the authentication service and the web site and is not responsible for the actual authentication or authorization of users. Pubcookie does not verify who the user is - it hands this task off to a separate authentication service (like Kerberos). Likewise, Pubcookie does not decide if a user should be allowed to access a given page or resource. Control of access to the resource is left to the originating application (usually by way of the .htaccess file).

This is accomplished, as the name implies, with cookies. When a user initially attempts to access a protected site (Arrow #1), the Pubcookie module at that site automatically redirects her browser to a Pubcookie login page with a granting request cookie containing the request (the URL) and a random number (#2). The user enters her user name and password on the login page (#3), which Pubcookie verifies using the configured authentication service (#4 and #5). Pubcookie then returns two cookies to the user's browser (#6) and redirects the user back to the original site (#7).

The first of these cookies returned in step #6 is a granting cookie. This cookie authenticates the user to the target web site ("Pubcookie-enabled Application Server"). The cookie contains the information in the original granting request cookie plus the authenticated username. When the Pubcookie login server redirects the browser back to the original web site (#7), the Pubcookie module at the web site verifies the web page. If the user is authorized, the web server returns the requested content (i.e., the web page) with a session cookie for that site to authenticate subsequent requests at that site (#8).

The second cookie returned by the login server is the Pubcookie session cookie. As its name implies, this is the cookie that the user maintains throughout their Pubcookie session. When the user visits a new Pubcookie-enabled web site, it will again redirect her to the Pubcookie login server. However, now that the user has a Pubcookie session cookie, she does not have to login again (Steps #4 and #5). The login server verifies the session cookie and automatically redirects the user back to the new web site with a new granting cookie. Thus, the user has a single sign-on to all Pubcookie-enabled web sites.

There are two means by which the security of these cookies is guaranteed. First, they are encrypted. When Pubcookie is being setup, the Pubcookie login server (which issues the cookies) and the application server (i.e., the web server the user is trying to access) exchange a cryptographic key (see setup instructions below). This key is in turn used to encrypt and decrypt the data used by Pubcookie. The second method by which security is achieved is digital signatures. The Pubcookie login server digitally signs all cookies it issues, so that application servers can use the login server's public key (see setup instructions below) to verify the authenticity of the cookies it issues.

The following steps explain the process for setting up a site to utilize Pubcookie at ISU.

The module relies on additional infrastructure at your site. Here are some
general prerequisites that, if fulfilled, will lead to a smooth, successful
installation:

* Determine the location of your site's Pubcookie login server. You'll need
this URL to configure the module. You may also want to find out its
version, so that you know what features it supports.

* Determine the location of your site's Pubcookie keyserver. You'll need
this URL to request a symmetric encryption key that your server will share
with your login server. Depending on the keyserver version and site policy,
you may also need to ask your administrator to "permit" your server to
request keys. (Go back to the conceptual explanation above)

* Determine how trust is handled by your site's Pubcookie keyserver. You'll
need to know which Certificate Authorities the keyserver trusts to verify
certificates. Similarly, you'll need to know which Certificate Authority can
verify the keyserver's certificate. Ask your administrator for guidelines;
it'll save you time and effort.

* Determine how your site distributes its Pubcookie "granting" certificate.
You'll need a copy of this certificate (file) to verify the "granting" cookies
signed and sent by your site's login server. You may be able to download it
from your keyserver, or you may have to obtain it manually. Ask your
administrator which method to use. (Go back to the conceptual explanation above)

# 1 is a good starting point
logging_level: 1

# ssl config
ssl_key_file: /etc/httpd/conf/ssl.key/server.key
ssl_cert_file: /etc/httpd/conf/ssl.crt/server.crt

# keyclient-specific config
keymgt_uri: https://weblogin.iastate.edu:2222
ssl_ca_file: /usr/share/ssl/certs/ca-bundle.crt

keydir: /usr/local/pubcookie/keys

PubcookieAppID protected
AuthType NetID
require valid-user

LoadModule pubcookie_module modules/mod_pubcookie.so

#
# Pubcookie configuration section
#

PubcookieGrantingCertFile /usr/local/pubcookie/keys/pubcookie_granting.cert
PubcookieSessionKeyFile /etc/httpd/conf/ssl.key/server.key
PubcookieSessionCertFile /etc/httpd/conf/ssl.crt/server.crt
PubcookieLogin https://weblogin.iastate.edu/
PubcookieDomain .iastate.edu
PubcookieKeyDir /usr/local/pubcookie/keys/
PubcookieAuthTypeNames NetID

# Disable inactivity timeout by default
<Directory "/var/www/html">
PubcookieInactiveExpire -1
</Directory>
<Directory "/var/www/cgi-bin">
PubcookieInactiveExpire -1
PubcookieHardExpire 3600
</Directory>

<LocationMatch .*/LOGOUT-REDIRECT>
AuthType NetID
require valid-user
PubcookieEndSession redirect
</LocationMatch>

<LocationMatch .*/LOGOUT-CLEARLOGIN>
AuthType NetID
require valid-user
PubcookieEndSession clearLogin
</LocationMatch>