Pubcookie Home > Documentation 
 
Pubcookie
Design Specifications
Modified:  February 20, 2003

Note: These specifications are not up-to-date. Pubcookie does a number of things differently from, or in addition to, what is described below.

Included on this page:

Overview

The Web authentication service, aka "Pubcookie", uses three cookies to provide single sign-on, cross Web server authentication. The ancestral namesake of Pubcookie was a cookie scoped to the entire washington.edu domain. The immoderately public nature of this cookie led to several descendants: a cookie that is shared only with the login server (the login cookie), a cookie that is shared only with the application server (the session cookie), and a shortly lived serialized cookie that is shared more widely (the granting cookie).

The login cookie is used to identify the user to the login server. The granting cookie is issued by the login server after the user has authenticated and is used on the initial access to the application server. Once the user has accessed the application with a valid granting cookie, a session cookie is established for the remainder of the application session (or until it times-out).

Application Server

Overview

The application server is a Web server hosting an application. The application server must satisfy requirements enumerated in the requirements section.

Application Server Logic

  • Does the request have a valid session cookie?
    • Yes: Is the request within the inactivity and hard timeouts?
      • Yes: Satisfy request and send cookie with updated last visited timestamp.
      • No: Redirect to login server.
    • No: Does the request have a valid granting cookie for me (validated granting cookie with 'server identifier' in the appserver ID field of the cookie)?
      • Yes: Is the granting cookie within the cookie granting timeout window?
        • Yes: Issue session cookie, empty out granting cookie, and satisfy request.
        • No: Redirect to login server.
      • No: Redirect to login server.

Validating Session Cookies

  • Signature is verified (implies decoding and message integrity check)
  • Correct software version

Validating Granting Cookies

  • Signature is verified
  • Correct Software version
  • Appserver ID field is Server Identifier

Server Identifiers

Server identifier is a per Web cluster identifier that is sent to the login server with the granting request, then put into granting cookie.

Login Server

Overview

The login server is a Web server that hosts the login page, login credential authentication, and cookie generation code.

Login Server Logic

When the login cgi receives a valid granting request with a valid login cookie, a granting cookie is created and the client is redirected to original request. If the granting request is invalid, an error is returned stating that the application server has made an invalid login server request and the application server's administrator should be contacted. If there is no valid login cookie, the login page is presented. If credentials are valid a granting cookie is sent and the client is redirected to original request.

Validating Granting Requests

Valid software version, undefined at this time. The option exists to refuse service to older or non-compliant software versions.

Validating Login Cookies

  • Within Login timeout
  • Signature is verified (implies decoding and message integrity check)

Timeouts

Login

  • Interval for user to be re-prompted for credentials
  • Based on timestamp in login cookie
  • Timeout is eight hours
  • Not configurable by the application

Application

  • Interval for user to be redirected to login server.
  • Inactivity and hard timeout.
  • Based on timestamps in session cookie. Session cookie has creation and last visit timestamps. Creation timestamp is set on first generation of the session cookie. Last visit timestamp is updated on every request.
  • Inactivity and hard timeout are configurable by the application.
  • Default inactivity timeout is 30 minutes.
  • Default hard timeout is eight hours.
  • Can be overridden with directives.
  • Inactivity timeout can be turned off.

Granting

  • Interval from issue of granting cookie while it's still acceptable to establish a application session
  • First guess granting timeout is ten seconds; could change when the timing of the redirection is better known

Cookies

Cookie Trinity

The roles of the three cookies are described in the overview section.

Cookie Type Scope Timeout
Granting .washington.edu granting timeout
Login Login Server login timeout
Session Application Server application timeout

Cookie Contents

The inner cookie structure is fixed length:

char[42] Authenticated UW NetID

Currently a UW NetID. (It could be full Kerberos principal.)

time_t Creation Time

Timestamp of cookie creation. Seconds from 1/1/70 (obsolescence planned by 2038). Used as granting timeout, login, and session hard timeout (see timeouts).

time_t Last Visit Time

Timestamp of last request from application server. Only used in session cookie. Only used for inactivity timeout. Seconds from 1/1/70 (see timeouts).

char Credential Array

Allows for eight possible credentials to authenticate UWNetID or combinations.

0x01 - Kerberos password
0x02 - SecurID
0x03 - Reserved for MCIS

int Cookie Type

1 - Granting
2 - Session
3 - Login

int Serial Number

Used to detect and deny reused or misused cookies.

char[20] Appserver ID

Server identifier is a per Web cluster identifier that is sent to the login server with the granting request then put into granting cookie.

int[2] Software Version

Major and minor version numbers, allows versioning control. May be used to require module upgrades. Granting requests will be stamped with module application version.

Signature

The inner cookie is signed. A 128-byte signature of the inner cookie is generated using a RSA private key and an MD5 hash. Currently the EVPSign routines from OpenSSL are used (see http://www.openssl.org or http://www.psy.uq.oz.au/~ftp/Crypto).

Encoding

The inner cookie and signature are encoded with a symmetric encryption algorithm with the keys algorithmically derived at run time.

SSL Required

Additionally, the cookie is ASCII encoded and marked so that it will only be passed back and forth on SSL connections.

Redirection

Application Server to Login Server (Granting Request)

When the Application server needs to send the user back to the login server, it issues an 302 moved temporarily response code. The location redirected to is the login cgi on the login server. The request is a cgi GET with granting request information in the GET fields.

The following information is forwarded with the granting request:

  • Requesting appserver's server identifier
  • Pubcookie module version from requesting appserver's
  • Possibly more logging information (server name, Web server version platform, etc.)
  • Authentication credentials requested (Kerberos password, SecurID, etc.)
  • Original URL

Login Server to Application Server (Granting Reply)

Once the user is authenticated (either by entering valid credentials or supplying a valid login cookie) the first page returned sends the cookies and has a zero second META refresh. The page that is refreshed is a http 302 redirect to the original URL. This double request/reply possibly could be cleaned up with JavaScript.

Granting Request

The granting request is sent to the login server in a base64 encoded cookie with the following fields:

Field Label Description Example
PBC_GETVAR_APPSRVID Application server name www.washington.edu
PBC_GETVAR_APPID Application ID My Authenticated App
PBC_GETVAR_CREDS Credential array 1
PBC_GETVAR_VERSION Version a4
PBC_GETVAR_METHOD Method GET
PBC_GETVAR_HOST Web server hostname www1.cac.washington.edu
PBC_GETVAR_URI URI of return URL /pubcookie/sample_index
PBC_GETVAR_ARGS Arguments arg1="fruit"&arg2="banana"

The GET arguments are taken from the return destination URL.

The Login Loop

When a session cookie is insufficient to authenticate a request, the user is sent through the login loop.

Application Server Preparation for the Login Loop

Any GET arguments in the request that causes the login loop are base64 encoded into one ASCII blob and put into the granting request cookie, which is also base64 encoded.


[Pubcookie Home Page]
Copyright © 2002-2008 University of Washington
UW Technology Services
Pubcookie Contact Info
Modified: February 20, 2003