| 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:
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).
The application server is a Web server hosting an application. The application
server must satisfy requirements enumerated in the requirements section.
- 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.
- Signature is verified (implies decoding and message integrity check)
- Correct software version
- Signature is verified
- Correct Software version
- Appserver ID field is Server Identifier
Server identifier is a per Web cluster identifier that is sent to the login
server with the granting request, then put into granting cookie.
The login server is a Web server that hosts the login page, login credential
authentication, and cookie generation code.
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.
Valid software version, undefined at this time. The option exists to refuse
service to older or non-compliant software versions.
- Within Login timeout
- Signature is verified (implies decoding and message integrity check)
- Interval for user to be re-prompted for credentials
- Based on timestamp in login cookie
- Timeout is eight hours
- Not configurable by the 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.
- 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
The roles of the three cookies are described in the overview section.
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.
|
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).
The inner cookie and signature are encoded with a symmetric encryption algorithm
with the keys algorithmically derived at run time.
Additionally, the cookie is ASCII encoded and marked so that it will only be
passed back and forth on SSL connections.
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
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.
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.
When a session cookie is insufficient to authenticate a request, the user is
sent through 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]](/img/41x35-rings-only.gif){kind=small}
