| This overview describes how Pubcookie works at version 3.0.
Included on this page:
Components & Roles
The Pubcookie model of user authentication is based on: a
User-Agent, Pubcookie's two server components, and an external
authentication service. Servers are classified as "login"
or "application" servers. Examples of external authentication
services include Kerberos, LDAP, and NIS. The User-Agent is
most often represented by a user's web browser.
The role of the Pubcookie login server is that of the trusted,
central authentication service. It interacts directly with
users. It verifies usernames and passwords with backend authentication
services. It issues cookies to users to provide single sign-on
functionality and to application servers to provide authentication
The role of the Pubcookie application server is that of authentication
enforcer. It redirects users who haven't been authenticated
to the login server. It verifies authentication information
returned from the login server. It issues cookies to users
to maintain authenticated application sessions and provides
user authentication information to applications.
The role of the external authentication service is to verify
user authentication information sent to it from the login
The role of the User-Agent in all of this is simply to play
along: to carry the user to the login server when redirected
to do so, to assist the user by rendering the HTML-based user
interface of the login server, and to accept all valid cookies
set by the login and application servers.
Setup & Configuration
Pubcookie-based authentication begins with the setup and
configuration of a Pubcookie login server and at least one
Pubcookie application server that hosts at least one Pubcookie-protected
During the setup phase, the login server and application
server negotiate a shared, symmetric key, and the login server's
public key is copied to the application server. Additionally,
each application server is configured with the location of
its login server and other site-specific details.
The User-Agent requires no setup. Standard browser configurations
Initial Sign-on Process
The intial sign-on process (i.e. how a user is initially
authenticated) is illustrated in the following diagram; each
step is explained in detail below the diagram. Redirection
between servers is represented with dashed horizontal lines.
A user makes a request to an application server for
a resource (a URL) tied to an application that uses Pubcookie
The Pubcookie module intercepts the request and inspects
it to determine that the request is not associated with
a valid, existing authenticated session for the application
and does not carry information from the login server (known
as a "granting cookie", see steps 8 and 9) necessary to
establish a new session.The Pubcookie module generates
a response, including a "redirect" page and two cookies:
a "pre-session" cookie scoped to the application,
and a "granting request" cookie scoped to reach
the login server. Both cookies contain, among other things,
a random number generated by the Pubcookie module.
The "redirect" page causes the user's browser to make
a request to the Pubcookie login server, including the
"granting request" cookie.This is the "granting
request". It contains information about the application
server, the original resource (URL), the desired type
of authentication, etc.
The Pubcookie login server decodes the "granting
request" cookie and interprets the contents. In response,
it generates a login form page and sends it to the browser,
prompting the user to enter username and password.
The user enters his or her username and password into
the form and submits it, causing the browser to send the
data to the login server.
The Pubcookie login server takes the username and password
and sends them to its backend authentication service for
The Pubcookie server receives the verification response.
If verification is successful, the Pubcookie login server
generates a response, including a "redirect"
page and two new cookies. (If verification fails, another
login form page is sent to the user's browser.) One cookie,
known as the "granting cookie", contains the authenticated
username and some other items, including the random number
it received from the application server via the "granting
request". The "granting coookie" is protected
from tampering by being signed using the private key of
the login server, and protected from disclosure by being
encrypted using the symmetric key shared by the application
server and the login server. It is scoped to reach the
application server. The second cookie, known as the "login
cookie", is scoped to the login server and will be
used on any subsequent visits by the user to the login
The "redirect" page causes the user's browser
to re-request the original resource (URL) on the application
server. This request contains the granting cookie set
by the login server and the "pre-session" cookie
set earlier by the application server.
The Pubcookie module on the application server again
intercepts the request, as in step 2. This time it finds
the "granting cookie" which it decrypts using the shared
symmetric key. It then verifies the signature using the
login server's public key and matches the random number
found in the "granting cookie" with the random
number found in the "pre-session" cookie. If verification succeeds, the Pubcookie module supplies
the authenticated username to the application along with
the rest of the original request. It also generates a
valid "session cookie" for subsequent requests
by the user to the application. Having successfully authenticated the user, the application
can finally send the original resource to the user. The
Pubcookie module makes sure that the application's response
is accompanied by the new "session cookie".
If, in step 4, the "granting request" is accompanied
by a previously established, valid "login cookie"
(as set in step 8), then steps 5, 6, and 7 are skipped, and
the login server proceeds to step 8, issuing a "granting
cookie" using the username as found in the "login
cookie". This provides the "single sign-on" experience
for the user, allowing him or her to request resources tied
to other Pubcookie-authenticated resources without having
to re-enter a password as long as the "login cooke"
is still valid (e.g. for 8 hours after the intial sign-on).
A user's best, most effective method of logging out supercedes
that which is provided by Pubcookie itself. Specifically,
if a user quits his or her User-Agent or logs out of his or
her operating system, all open sessions maintained by Pubcookie
will be closed. The underlying assumption is that these user-driven
events always clear the cookies that Pubcookie uses to maintain
state. However, on some platforms and in some circumstances
(see known problems) this assumption is not valid, and other
means of logging out must be made.
Pubcookie supports its own logout functionality too. Each
application can configure a specific resource (URL) that,
when requested by a user, will clear the application's current
"session" cookie. Each application can also configure
how it wants to respond to such logout requests. It can produce
its own response or it can redirect the user to the login
server which will generate a custom logout message on the
application's behalf. The latter method provides better consistency
among applications and a single point of convergence, at the
login server, for other edifying messages, such as the state
of the user's single sign-on session with the login service
Therefore, Pubcookie's logout functionality works on a "per-application"
basis not a comprehensive "global" basis. Using
this method, a user must manually log out of each application
plus the login server. It's much simpler to quit the browser.
Pubcookie's security model accounts for certain kinds of
"man in the middle" attacks. In order to do so,
it uses a shared symmetric key to encrypt certain messages
sent between each application server and the login server.
New keys are generated by the Pubcookie "keyserver"
application running on a site's login server. They are negotiated
and distrubuted using the Pubcookie "keyclient"
utility during the setup phase of each application server.
Keys are then maintained by the Pubcookie "keyserver"
application running on a site's login server. Keys can be
revoked at the login server, but automated expiration and
renewal processes are not yet provided.
- 2002/05/01 - original draft [RL Bob]
- 2002/05/24 - made diagram image [Wallenius]
- 2002/05/24 - various edits to align with diagram; add
- 2002/05/31 - more edits; turned into Web page [Dors]
- 2002/07/31 - added setup, config, roles [Dors]
- 2002/08/01 - another pass-thru of edits; random number
stuff added [Dors]
- 2002/08/04 - logout and key management added; new diagrams
- 2002/08/13 - clarified logout assumptions [Dors]