Contents 1 What is Pubcookie 2 How It Works 3 Installing Pubcookie 3.1 Prerequisites 3.1.1 Obtain a Valid Server Certificate 3.1.2 Download Certificate Authority Bundle 3.2 Configuring the Keyclient 3.2.1 Create a Config File 3.2.2 Allow Your Keyclient to Talk to the Master Server 3.2.3 Obtain Keyserver Granting Certificate 3.3 Configure mod_pubcookie 3.3.1 Enable Module in Apache 3.3.2 Set Global Configuration Variables 3.3.3 Protecting a Resource 3.4 Virtual Host Configuration Steps

[edit] What is Pubcookie

Pubcookie is an Apache module that allows web sites to implement a Single Sign-On service. Case initially used Pubcookie as a single sign-on solution, but switched to CAS in August 2005 because CAS is much easier to implement than Pubcookie.

[edit] How It Works

Pubcookie is configured as the authentication method for a protected resource. When a user requests this resource, Pubcookie goes to work.

More soon.

[edit] Installing Pubcookie

[edit] Prerequisites

[edit] Obtain a Valid Server Certificate

The keyclient needs a certificate generated by a valid certificate authority in order to communicate with the central keyserver. Self-signed certificates will not work.

For the remainder of this document, it is assumed that this valid key and certificate are:

/etc/apache/ssl.key/server.key
/etc/apache/ssl.crt/server.crt

[edit] Download Certificate Authority Bundle

https://its-services.case.edu/middleware/src/case-ca-bundle.crt

For the rest of this document, we assume the file is saved as

/etc/apache/ssl.crt/ca-bundle.crt

[edit] Configuring the Keyclient

The keyclient resides on each individual server (piece of hardware) that runs Pubcookie. The keyclient can service mutliple instances of Apache, so it only needs to be installed once. The keyclient is called by Pubcookie and is the component that talks to login.case.edu.

[edit] Create a Config File

The filename for the config file is $PREFIX/config. The file should be in the same directory as the keyclient binary.

Add the following lines to the config file:

ssl_key_file: /etc/apache/ssl.key/server.key
ssl_cert_file: /etc/apache/ssl.crt/server.crt

keymgt_uri: https://login.case.edu:2222
ssl_ca_file: /etc/apache/ssl.crt/ca-bundle.crt

[edit] Allow Your Keyclient to Talk to the Master Server

The keyclient cannot talk to the keyserver without manual intervention. The keyserver must be set to allow connections from a specific hostname AND from a keyclient connecting with a certificate signed by a trusted certificate authority.

To request permission to talk to the Pubcookie keyserver, e-mail certificate-admin@case.edu with the hostname of the machine running the keyclient.

Once you have heard back from the certificate administrators, it is time to talk with the keyserver. To obtain your private communication key, simply run

keyclient

This will save a key in the keys/ subdirectory under where the keyclient binary is located. The filename will be the same as the hostname you requested the keyserver administrators to allow access.

[edit] Obtain Keyserver Granting Certificate

The next step is obtaining the granting certificate from the keyserver. The granting certificate says that you have been delegated the authority to authorize users against the keyserver.

Download the granting certificate by running

keyclient -G login.case.edu_granting.crt

This will save the granting cert to the filename specified. Remember this file name.

[edit] Configure mod_pubcookie

[edit] Enable Module in Apache

You must set Apache to load the module. This is done with the LoadModule directive.

LoadModule pubcookie_module   mod_pubcookie.so

[edit] Set Global Configuration Variables

You will need to set the following global variables in your Apache config:

• PubcookieAuthTypeNames
  • This is the string to register with Apache's AuthType directive
  • e.g. PubcookieAuthTypeNames CasePubcookie
• PubcookieGrantingCertFile
  • The granting certificate file for the keyserver
  • e.g. PubcookieGrantingCertFile login.case.edu_granting.crt
• PubcookieLogin
  • The login server to use
  • This will always be https://login.case.edu
• PubcookieDomain
  • The domain associated with the login server
  • This will always be .case.edu
• PubcookieSessionKeyFile
  • The key file used by keyclient
  • This must be the same key specified in the keyclient config file
• PubcookieSessionCertFile
  • The certificate used by the keyclient
  • This must be the same certificate specified in the keyclient config file
• PubcookieKeyDir
  • The directory where the server's private keys are stored
  • e.g. /etc/apache/ssl.key/

These directives MUST be specified in the global portion of the config file.

An example Pubcookie configuration would resemble the following:

 
LoadModule pubcookie_module usr/lib/apache2/mod_pubcookie.so
PubcookieAuthTypeNames CasePubcookie
PubcookieGrantingCertFile /var/pubcookie/keys/login.case.edu_granting.cert
PubcookieLogin https://login.case.edu
PubcookieDomain .case.edu
PubcookieSessionKeyFile /etc/apache/ssl.key/blog-dev.case.edu.key
PubcookieSessionCertFile /etc/apache2/ssl.crt/blog-dev.case.edu.crt
PubcookieKeyDir /var/pubcookie/keys/

[edit] Protecting a Resource

Protecting a resource using Pubcookie is rather painless. Using the example config above, you could limit access to any user authenticating against the login server by including the following:

 
  AuthType CasePubcookie
  AuthName "Case Network ID"
  require valid-user

[edit] Virtual Host Configuration Steps

A virtual host setup will not work if the above is not working. It is imperative that the above work before even attempting to configure virtual hosts.

When running keyclient with no arguments, you obtain the symmetric encryption key from whatever hostname is associated with the key and certificate defined in the config file. To override which pair to use without editing the config file, we pass keyclient some arguments.

-k filename

overrides the key file to use.

-c filename

override the certificate file to use.

If we had foo1.key and foo1.cer defined in the config file, we could obtain the symmetric encryption key for hostname foo2 by running

keyclient -k foo2.key -c foo2.cer

Once this is done, for every named <VirtualHost> section in the Apache config, you must define PubcookieSessionKeyFile and PubcookieSessionCertFile to point the corresponding key and cert pair. Otherwise, the global values will be inherited and Pubcookie will fail to work.

This page has been accessed 4,878 times.
This page was last modified 12:08, August 18, 2005 by Gregory Szorc.
About | Disclaimers