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.

pubcookie-components How Pubcookie Works

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 information.

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 server.

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 application.

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 work well.

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.

pubcookie-iso-diagram How Pubcookie Works

  1. A user makes a request to an application server for a resource (a URL) tied to an application that uses Pubcookie for authentication.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. The Pubcookie login server takes the username and password and sends them to its backend authentication service for verification.
  7. The Pubcookie server receives the verification response.
  8. 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 server.
  9. 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.
  10. 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”.

Single Sign-on

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).

Logging Out

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 itself.

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.

Key Management

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.

Revision History:

  • 2002/05/01 – original draft [RL Bob]
  • 2002/05/24 – made diagram image [Wallenius]
  • 2002/05/24 – various edits to align with diagram; add headings [Dors]
  • 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 [Dors]
  • 2002/08/13 – clarified logout assumptions [Dors]