alpine.tar.z web/src/pubcookie/README
/* ========================================================================
 * Copyright 2006-2008 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * ========================================================================
 */

WEB ALPINE WITH PUBCOOKIE SUPPORT
---------------------------------

UW Pubcookie <http://www.pubcookie.org> provides single-sign-on
service for web-based applications.

For building and installation comments, see web/src/pubcookie/INSTALL.


WEB ALPINE PUBCOOKIE COMPONENTS
-------------------------------

Below are the extra binary helper applications and their descriptions
necessary to implement UW Pubcookie authentication within Web Alpine.

bin/wp_uidmapper:
	wp_uidmapper runs in background. Keeps pubcookie
	username <-> uid tables. Handles requests from
	wp_tclsh and wp_gssapi_proxy through the named socket
	/tmp/wp_uidmapper. This needs to be manually started,
	should never stop running, and should run as the same
	uid as the web server (nobody).

bin/wp_tclsh:

	wp_tclsh is a modified version of tclsh (8.0.5) that
	does a setuid before doing the tcl stuff. The tcl
	scripts directly run by the web server should use this
	as their #! interpreter. If REMOTE_USER is set
	(pubcookie in use) and the calling uid is the web
	server (nobody), it calls wp_uidmapper to obtain its
	destination uid. Otherwise, it just changes back to
	the calling uid.
	

bin/wp_gssapi_proxy:

	wp_gssapi_proxy is called by the c-client
	auth_gss_proxy.c routine, and does the GSSAPI/SASL
	dance with the imap server. Looks up the username
	corresponding to the calling uid via wp_uidmapper, and
	will fail if the calling program is requesting access
	to a different username's mail on the imap
	server. Compile time options for wp_gssapi_proxy:

		-DDDEBUG: outputs extra info to the syslog mail log.
		-DNO_UIDMAPPER: calls getpwuid(getuid()) to look up
			username of calling uid.

bin/alpined

	auth_gss_proxy.c is the c-client authenticator that calls
	wp_gssapi_proxy. Stick this in the imap/src/c-client directory
	of the pinetcl source tree. Make sure the
	AUTH_GSS_PROXY_PATH #define points to the location of
	the installed wp_gssapi_proxy. The following lines
	should be added to main() function in pine/pinetcl.c:

		/* put this auth_link at the beginning of the list */
		auth_link(&auth_gss_proxy);		
		/* try to get username from REMOTE_USER (pubcookie) */
		if(user = getenv("REMOTE_USER")) env_init(user,"/");

*.tcl:

	The scripts directly run by the web server must be
	changed to point to wp_tclsh instead of the normal
	tclsh. If for some reason you want to create a script
	that should be run as the web server uid, use the
	default tclsh interpreter. There is a script
	bin/chscriptinterp, which you can run as follows to
	change *.tcl to use /www/test/bin/wp_tclsh instead of
	whatever they currently use.

.htaccess: 

	AuthType UWNetID
	AuthName "Webpine"
	PubcookieAppId "Webpine"
	require valid-user

    NOTE: to properly scope the pubcookie cookie for the web server, 
          remove the PubcookieAppId directive

logout/.htaccess: 

	PubcookieEndSesion redirect
	
etc/webpine.keytab:

	Should be owned by nobody.nobody with 600 permissions. A cron
	entry for user nobody should run kinit often enough so that
	the ticket never expires:

	[root@server /]# crontab -u nobody -l
	# DO NOT EDIT THIS FILE - edit the master and reinstall.
	# (/var/spool/cron.new/nobody installed on Tue Dec  5 16:26:14 2000)
	# (Cron version -- $Id: README 910 2008-01-14 22:28:38Z hubert@u.washington.edu $)
	MAILTO=root@your-server-name
	0 3,11,19 * * * /usr/local/bin/kinit -k -t /www/test/etc/webpine.keytab webpine

debug.cgi:

	If you are having weird problems, run this via your web
	browser, and it might help you figure things out. Runs as the web
	server uid (nobody) and displays the following:

	- output of 'klist'
	- output of 'ps auxww |grep wp_uidmapper'
	- the environment
	- also lists any processes running as uids with no
	  corresponding usernames, which should tell you if your
	  pinetcl process is crashing.
		
	It also will restart wp_uidmapper if /tmp/wp_uidmapper does not
	exist, should that have crashed for some reason.

	Finally, visit debug.cgi?stop (via the web browser) and it
	will stop a currently running wp_uidmapper, so that you can
	restart it in case you do something like move the location of
	the binary.

-- 
$Id: README 910 2008-01-14 22:28:38Z hubert@u.washington.edu $