Included on this page:
This guide walks University of Washington web server administrators through the process of installing, configuring, and testing mod_pubcookie 1.77. Configuration instructions are specific to the way that Pubcookie is deployed at the UW.
Here are the significant changes introduced in mod_pubcookie 1.77:
supports per-application logout features (actually a version 1.69 feature, but who's counting) via the PubcookieEndSession directive; see Configuring Logout for Pubcookie-Protected Websites for details;
introduces and requires the PubcookieAuthTypeNames directive, which helps other sites besides the University of Washington use Pubcookie.
When upgrading to version 1.77 you must add a PubcookieAuthTypeNames directive to your httpd.conf if you don't already have one. Apache will not start if you do not define this mod_pubcookie setting. Refer to the configuration section below for details. All other configuration (keys, certs, etc.) is the same.
You do not need to request a new c_key if you already have a working Pubcookie installation.
Before you begin:
Make sure your server meets all of the system requirements. Accurate system time is particularly important.
Verify that SSL connections to your server are working by opening your home page via https. E.g.:
https://appserver.washington.edu/
C&C SSL Certificate Policy:
For use with Pubcookie at the UW, servers must have a SSL server certificate signed by either:
a well-known public CA such as Thawte (purchasing tips here), DST, or Versign;
or one signed by the UW Services CA.
General guidelines for adding SSL support to Apache:
If your Apache server does not already support SSL, here are some guidelines for adding it. Note: this is just an overview; you'll have to look elsewhere for specific instructions if you need them.
Build and install OpenSSL.
Compile Apache with SSL support by following the directions accompanying the mod_ssl or Apache-SSL source.
Generate a private key and obtain a SSL server certificate and install them as directed by the mod_ssl or Apache-SSL documentation.
Build and install Apache. This is when you will decide to build modules dynamically or statically. Be sure apxs (the Apache DSO module builder) is linked with OpenSSL.
Verify that Apache with SSL support works before you proceed to build mod_pubcookie.
You have the usual options for building mod_pubcookie. It can be built as a Dynamic Shared Object (DSO) or it can be built into Apache itself (statically linked).
To build mod_pubcookie as a DSO using apxs:
Download the mod_pubcookie distribution.
Unzip and untar the mod_pubcookie distribution files.
% gunzip -c mod_pubcookie-1.77.tar.gz | tar xvf -
Edit Makefile.apxs for your environment. For example, change the value of APXS to the location of the apxs executable; change SSL_BASE to the location of your OpenSSL libraries.
% pico Makefile.apxs
Build the DSO module using Makefile.apxs.
% make -f Makefile.apxs
Copy the module to your module library directory. For example:
% cp mod_pubcookie.so /etc/httpd/modules
Edit your Apache server configuration file (httpd.conf), adding LoadModule and AddModule directives for mod_pubcookie to the appropriate sections. These directives often go right before SSL. For example:
<IfDefine HAVE_SSL> LoadModule pubcookie_module modules/mod_pubcookie.so LoadModule ssl_module modules/libssl.so </IfDefine> ... <IfDefine HAVE_SSL> AddModule mod_pubcookie.c AddModule mod_ssl.c </IfDefine>
Again, this is just an example. Your httpd.conf may differ.
To build mod_pubcookie as a built-in (statically linked) module:
Download the mod_pubcookie distribution.
Unzip and untar the Pubcookie distribution files where you would put other modules, e.g.:
% cd /usr/local/src/apache_1.3.xx/src/modules
% zcat (download_dir)/mod_pubcookie-1.77.tar.gz | tar xf -
If you use the top level Apache Configure script, you will need to add the following option to configure it:
--activate-module=src/modules/pubcookie/mod_pubcookie.a
Or, if you use a src level Configure script, add an AddModule directive for pubcookie to the Configuration file and run the Configure script.
After running the configure scripts, do a 'make' to create a new Apache daemon with mod_pubcookie now statically linked in.
Several keys and certificates must be generated and installed as part of the mod_pubcookie installation process.
Note: if you are upgrading from a previous working installation of mod_pubcookie, you can reuse the keys and certs you already have.
Create a directory for keys and certificates:
Choose a good location for the keys and certificates used by mod_pubcookie. We'll call it the pubcookie directory. The default is /usr/local/pubcookie, so, e.g.:
% mkdir /usr/local/pubcookie
Non-privileged accounts should not be able to access files in this directory.
To request and install a crypt key file (c_key) for your server:
Note: if you are upgrading from a previous working installation of mod_pubcookie, you do not have to request a new c_key.
Determine the IP address of your Apache server. This is very important.
Request a crypt key file (c_key) for your server from pubcookie@cac.washington.edu. Include your name, phone number, and the IP address and domain name of your Apache server. C&C's Pubcookie team will respond to you shortly afterwards.
Place the c_key file in your pubcookie directory, e.g.:
% mv c_key /usr/local/pubcookie
During configuration, this file corresponds with the PubcookieCryptKeyfile directive.
To install the UW NetID "weblogin" service's granting certificate:
Note: if you are upgrading from a previous working installation of mod_pubcookie, you can continue to use your current copy of this cert.
Download the pubcookie_granting.cert for the UW NetID "weblogin" service.
Place pubcookie_granting.cert in your pubcookie directory, e.g.:
% mv pubcookie_granting.cert /usr/local/pubcookie
During configuration, this certificate corresponds with the PubcookieGrantingCertfile directive.
To create and install your session key pair:
Note: if you are upgrading from a previous working installation of mod_pubcookie, you do not have to regenerate this key pair. You can continue to use what you already have.
Generate a key pair for signing session cookies. For example, using openssl:
% openssl req -new -x509 -nodes -out file-for-cert.cert \ -newkey rsa:1024 -keyout file-for-key.key
If you already have a private key, you can use something like:
% openssl req -new -x509 -nodes -out file-for-cert.cert \ -key file-with-key.key
During configuration, file-for-key.key (or file-with-key.key) corresponds with the PubcookieSessionKeyfile directive and file-for-cert.cert corresponds with the PubcookieSessionCertfile directive. Example filenames used below are pubcookie_session.key and pubcookie_session.cert, respectively.
Copy your PubcookieSessionKeyfile and PubcookieSessionCertfile to your pubcookie directory, e.g.;
% cp file-for-key.key /usr/local/pubcookie/pubcookie_session.key % cp file-for-cert.cert /usr/local/pubcookie/pubcookie_session.cert
The final stage of the installation process is to configure Apache with the directives required by mod_pubcookie. It is also a chance to add any system-wide configuration you want.
To configure the necessary mod_pubcookie directives:
Edit your Apache server configuration file (httpd.conf), e.g.:
% pico httpd.conf
Add a new section for Pubcoookie configureation directives. mod_pubcookie generally requires the following directives:
# Pubcookie Configuration PubcookieCryptKeyfile /usr/local/pubcookie/c_key PubcookieGrantingCertfile /usr/local/pubcookie/pubcookie_granting.cert PubcookieSessionCertfile /usr/local/pubcookie/pubcookie_session.cert PubcookieSessionKeyfile /usr/local/pubcookie/pubcookie_session.key PubcookieLogin https://weblogin.washington.edu/ PubcookieInactiveExpire -1 PubCookieAuthTypeNames UWNetID null SecurID
Adjust the paths and filenames appropriately. The first four directives should be set according to the location and filenames from the previous section. For a definition of each directive, refer to the Pubcookie configuration directives reference.
Note: the PubcookieAuthTypeNames directive is new in mod_pubcookie 1.77 and it is required. It defines the strings that mod_pubcookie enables as new arguments to the AuthType directive.
It's likely that you'll want to permit the use of Pubcookie configuration directives in the context of .htaccess files. To do so, you will have to adjust the AllowOverride directive in httpd.conf. A value of AuthConfig or All will allow the use of the PubcookieAppID directive. All other Pubcookie configuration directives that can be used in the .htaccess context must be permitted using the All value:
AllowOverride All
That's it for installation and configuration. Please start your server.
Optional Recommended Configuration For Abbreviated Domain Names
Because HTTP cookies must be scoped to a specific fully qualified domain, the use of abbreviated domain names (e.g. "appserver" instead of "appserver.washington.edu") causes Pubcookie some problems. To remedy this, you might use mod_rewrite to rewrite (and redirect) abbreviated domain names to fully qualified domain names. Here is a sample configuration (for httpd.conf):
RewriteEngine on
RewriteCond %{HTTP_HOST} !^$
RewriteCond %{HTTP_HOST} !\.washington\.edu
RewriteRule ^/(.*)$ https://%{SERVER_NAME}/$1 [L,R]
The above rule is for a https URLs only; you would need something similar for http URLs. You may need to add additional rules for subdomains (e.g. subdomain.washington.edu). Additionally, abbreviated domain names must be in your ServerAlias list.
To test the Pubcookie Apache module:
Create a new directory within your DocumentRoot. For example:
% cd /var/www/html % mkdir testapp % cd testapp
In this directory, create a new Web page:
pico index.html
Add a simple message to the file such as "Hello world - I'm Pubcookie-protected!!" and save it.
Create a .htaccess file:
pico .htaccess
Add the following directives to the .htaccess file:
AuthType UWNetID PubcookieAppID "TestApp" require valid-user
Note: using these directives in a .htaccess file requires the AllowOverride AuthConfig modification to httpd.conf mentioned in the Apache configuration section .
Start a Web browser and open the address for the test directory, e.g.:
https://appserver.washington.edu/testapp/
You should be redirected to the UW NetID "weblogin" service.
After you log in as requested, you will be redirected back to the test directory and you should see your "Hello world!" message. If you do, you correctly and successfully installed and configured Pubcookie. Enjoy!!
