Included on this page:
The Pubcookie login server has two primary functions: to authenticate users and to issue authentication tokens (granting cookies) consumed by Pubcookie-enabled target application servers. Authentication occurs either by checking user-provided credentials via a backend authentication service (Kerberos, SecurID, ...) or by verifying a token that was created on a previous visit to the login server. Example code to interface to an authentication system is provided.
The Pubcookie login server uses a CGI program to handle all HTTP requests. This CGI program, hereafter referred to as "the login cgi" or index.cgi, is compiled from C and is the central Pubcookie component. The login cgi displays the web page where users are asked to enter authentication credentials as well as other web pages that display error messages.
Due to the important nature of the Pubcookie login server, the only other services that should be run on the same system are those which receive an equally high level of scrutiny for security. As deployed at the University of Washington, the Pubcookie login server is powered by the Apache web server software. Other web server software which supports CGI and SSL should also work, but this supposition has not been tested.
The login cgi has a very simple interface for talking to backend authentication services.
Most sites will want to use the "basic" login flavor, which supports username/paassword single-sign-on authentication. (Currently no other flavors exist!)
The basic login flavor supports many different verifiers. Some of the ones shipped with pubcookie as of this writing are:
You can set which verifier to be used with the "basic_verifier" configuration parameter (see Run-time configuration). Some verifiers will allow or require further customization; see the section referring to that verifier.
Depending on your installation environment you may choose to install the login server in a number of configurations. Two general models are presented here with any necessary Apache configuration directives.
For a clean looking login URL you can install the login server to be the default file in a directory. The default filename, index.cgi, is a common name for a cgi file that would be executed when only directory URL is specified.
The University of Washington uses https://weblogin.washington.edu/ as the login server URL; it's very simple for users to identify in the browser's URL field.
The Apache config directive 'DirectoryIndex' tells Apache it how to handle requests for directories. See the mod_dir documentation for more information. When a request is made for a directory Apache will choose the first file it finds in the DirectoryIndex list.
Our DirectoryIndex line looks something like:
DirectoryIndex index.html index.cgi
If this is the configuration you choose, make sure there isn't an index.html file in the same directory as the index.cgi binary.
The login CGI is not name dependant and can be deployed as index.cgi, login.cgi, or some other CGI file if you like. In can also be put in any subdirectory you wish.
Your login server's URL could be something like https://www.example.edu/cgi-bin/login.cgi. Some sites may do this avoid the confusion with the default index page.
Depending how you want to configure things with Apache or which ever Web server you want to use for the login server, your login server URL could be something like https://www.myuniversity.edu/login where /login is mapped to the CGI program (index.cgi or whatever you rename it to).
The default login server and login URI are specified as "login_host" and "login_uri" in pubcookie configuration file. (Individual applications may override what login server they refer to with the PubCookieLogin directive in their apache configuration file, but this isn't recommended.)
Apache needs to know how to identify and handle cgi scripts. Some distributions of Apache will hav the cgi handler disabled, you will want to make sure the following line is in your httpd.conf and not commented out.
AddHandler cgi-script .cgi
This has been made easier with autoconf. (Thanks Jon Miner, University of Wisconsin!) To build a barebones login server, run:
$ ./configure --enable-login --disable-apache $ make $ make install
This sequence will build and install the index.cgi, keyserver, and keyclient binaries, using the default directory prefix (/usr/local/pubcookie, henceforth called {PUBCOOKIE_DIR}) and "alwaystrue" verifier.
To build the login server with other verifiers enabled (e.g. "kerberos_v5", "ldap", or "shadow") look at the configure options and adjust accordingly:
$ ./configure --help
Most configuration of the login server can be done at run-time via Pubcookie's config file. It is located at {PUBCOOKIE_DIR}/config and has "attr: value" lines throughout. A sample configuration file is included as config.sample. A complete explanation of all available options is available in the config documentation.
Some of the more notable variables are:
The following options should refer to the same files that your web server uses for SSL.
If your institution uses a single CA without any intermediate certificates, set ssl_ca_file to the path of the CA's certificate. If your institution uses multiple CAs or intermediate certificates, you'll need a directory (ssl_ca_path) contain those certificates named via their OpenSSL hashes. At least one of ssl_ca_file and ssl_ca_path should be specified.
See config.html for a full list of attributes.
The design of the login cgi preceded consideration of external use of Pubcookie, so there is much work to be done to improve flexibility and make it less specific to the University of Washington.
However, preliminary work has been done with login templates (specifying the look of each page the login CGI serves up) and the run-time configuration file. These pages should live in {PUBCOOKIE_DIR}/login_templates. We recommend you start with the files in src/login_templates.generic/ and customize them as you see fit. The Washington and CMU files (or an older version of them) is supplied for your amusement in src/login_templates.uw and src/login_templates.cmu respectively.
The {PUBCOOKIE_DIR}/ok_browsers file contains a list of acceptable browsers. The idea behind ok_browsers is to block browsers that either have a known security flaw (i.e. don't forget cookies when they should) or don't work with Pubcookie (i.e. Opera which doesn't do domain level cookie scoping correctly). IE and Netscape are the only two browser families that are known to work with Pubcookie.
So far we've been too chicken to really use the 'ok_browsers' functionality to block browsers that we know don't work. For now our ok_browsers has a single line: "Mozilla". Since both Netscape and IE claim to be Mozilla that covers the only two browsers known to work with Pubcookie. Proceed according to your own policy.
{PUBCOOKIE_DIR}/keys is the location of the keystore that the login cgi uses. The login cgi makes use of several different keys.
The pubcookie_login key and certificate are used to secure the "login cookie" that maintains the single sign-on session with the login server. These files are kept exclusively on the login server. We recommend that you reuse your existing private key and SSL server certificate rather than generating a new keypair. The login cgi will automatically do so if you set ssl_cert_file and ssl_key_file correctly.
Next, the pubcookie_granting keypair is needed to secure authentication assertions sent from login server to application servers, as represented by the "granting cookie". The key is kept exclusively on the login server; the certificate must be distributed to every application server.
$ openssl req -new -x509 -nodes \
-out /usr/local/pubcookie/keys/pubcookie_granting.cert \
-newkey rsa:1024 -keyout /usr/local/pubcookie/keys/pubcookie_granting.key
If you want to place these files in a different location (than {PUBCOOKIE_DIR}/keys/pubcookie_granting.{key,cert}), you'll need to set the granting_cert_file and granting_key_file attributes.
keyserver is a program that maintains DES keys. Unfortunately, due to subtleties in the key usage constraints, it is unable to run as a CGI underneath a login server. Instead, we recommend that it be run from inetd.
Add a line like the following to the login server's /etc/inetd.conf:
2222 stream tcp nowait root /usr/local/pubcookie/bin/keyserver keyserver
where /usr/local/pubcookie/bin/keyserver is where the keyserver binary is installed. Make sure that your pubcookie/config file is correctly configured.
If you are using xinetd, you should create a file named keyserver in /etc/xinetd.d with the following contents:
# description: pubcookie keyserver
service keyserver
{
type = UNLISTED
protocol = tcp
port = 2222
disable = no
socket_type = stream
wait = no
user = root
group = tty
server = /usr/local/pubcookie/bin/keyserver
}
After adding this line (or file), restart inetd.
Now run keyclient to generate a DES key for the login server:
% /usr/local/pubcookie/bin/keyclient
This will cause the keyserver program to generate a new DES key for the login server to use to provide confidentiality for the login cookies.
Generating DES keys for the application servers is just as easy as above---in fact, the exact same command works.
It is important that the application server's SSL certicate is signed by the same certificate authority as is configured in the login server's config file.
Remember that the application server will also need a correct 'config' file.
If you have an exisiting pubcookie installation using a shared DES key with hashed IP addresses, you can upgrade your login server without generating new keys on every application server.
On the login server, in the .../pubcookie/keys/ directory, make a copy of the master DES key (before hashing it to any IP address) for each application server, named with the full hostname of the server.
For example, create .../pubcookie/keys/oldappserver.example.edu containing the original DES keyfile.
The login server will use this key to encrypt data going to that application server, and the application server can continue to use it's key (XOR'd with it's IP address) to decrypt the data.
During the application server's next scheduled downtime, you can create a new unique DES key for that application, as in the Key management section above.
Sites frequently want several hosts configured identically to provide redundancy (either for performance or stability). In this section, we're assuming that you have a set of machines with an identical SSL certificate and key on them.
For instance, an institution might have 15 webmail servers named webmail1.example.edu through webmail15.example.edu with 15 unique IP addresses. All of them are equipped with a webmail.example.edu certificate and are behind a Cisco Load Director which controls the IP address for webmail.example.edu.
Use keyclient on webmail1.example.edu to generate a webmail.example.edu DES key. Use keyclient -d on all other webmail machines (webmail2.example.edu, etc.) to download an identical application key to the remaining servers.
pbc_create creates a pubcookie cookie, convenient for creating cookies ad hoc. Arguments come in via stdin and the cookie is put out on stdout. Args are space delimited, and in order: user appsrvid appid type creds serial crypt_file cert_key_file. Anything too big is just truncated, no support for defaults or anything like that. See src for details.
pbc_verify decrypts/verifies/displays pubcookie cookies, convenient for 'unbundling' a cookie and seeing what's inside. The arguments come in on the command line, the cookie comes in on stdid, and the contents are dumped to stdout. The required argument is cookie_type and the optional arguments are encryption_key and cert_file.
As an example you can use these two programs to do things like:
# echo "willey appsrvid appid 1 2 23 \
/usr/local/pubcookie/c_key /usr/local/pubcookie/test.key" | \
./pbc_create | \
./pbc_verify 1 /usr/local/pubcookie/c_key /usr/local/pubcookie/test.cert
and get something like
user: willey version: a5 type: 1 creds: 2 serial: 23 appsrvid: appsrvid appid: appid create_ts: 1006986719 last_ts: 1006986719
Copyright 1999-2002, University of Washington. All rights reserved.
See doc/LICENSE.txt for terms of use.
$Id: install-login.html,v 1.3 2002/10/02 21:41:00 dors Exp $