web/src/pubcookie/INSTALL

   1 alpine.tar.z web/src/pubcookie/INSTALL
   2 $id$
   3 /* ========================================================================
   4  * Copyright 2006-2008 University of Washington
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * ========================================================================
  13  */
  14
  15 STEPS TO ADD PUBCOOKIE SUPPORT TO WEB ALPINE
  16 --------------------------------------------
  17
  18 UW Pubcookie <http://www.pubcookie.org> provides single-sign-on
  19 service for web-based applications.  Web Alpine can be built to use UW
  20 Pubcookie within a Kerberos authorization framework.
  21
  22 Building Web Alpine to use pubcookie authentication should be
  23 accomplished by simply adding:
  24
  25     --with-pubcookie
  26
  27 and:
  28
  29     --with-web-bin=/usr/local/libexec/alpine/bin
  30
  31 to the configure script's command line.  Note, the value you supply in
  32 the second configure option is the directory where ultimately the Web
  33 Alpine's binary support tools will be installed.  In addition,
  34 Kerberos 5 must be available on the Alpine web server.
  35
  36 Installation of the extra binary components for pubcookie support
  37 should happen automatically.  After the "make install" command typed
  38 in web/src directory completes successfully, verify that:
  39
  40     web/bin/wp_uidmapper
  41     web/bin/wp_tclsh
  42     web/bin/wp_gssapi_proxy
  43
  44 all exist.  Then simply follow the normal Web Alpine installation
  45 steps described in the web/INSTALL document.
  46
  47 Once Web Alpine is installed, there is some additional configuration
  48 required.  First, you'll need to change permissions on a couple of the
  49 binary components as they do make use of the setuid() system call.  It
  50 should be simply a matter of:
  51
  52     cd /usr/local/libexec/alpine/bin
  53     sudo chmod 4755 wp_gssapi_proxy wp_tclsh
  54
  55 Next, you'll need to:
  56
  57     cd /usr/local/libexec/alpine/cgi/session
  58
  59 In that directory you'll need to edit the ".htaccess" file, adding the
  60 lines contained in the example htaccess file in the distribution's
  61 "web/src/pubcookie/_htaccess_session".
  62
  63 Then,
  64
  65     cd /usr/local/libexec/alpine/cgi/session
  66
  67 and edit the ".htaccess" file therein, adding the lines contained in
  68 the example file "web/src/pubcookie/_htaccess_session_logout".
  69
  70 Running Web Alpine with pubcookie requires some extra care and
  71 feeding.  First, the service provided by "wp_uidmapper" must be
  72 started and maintained as long as the web server is providing Web
  73 Alpine service.  It must be run under the same uid as the web server.
  74 The helper script "debug.cgi" can be used to conveniently
  75 start/restart the wp_uidmapper service.  Make sure the path defined
  76 within that script is correct for your system.
  77
  78 Finally, you'll need to create within the Kerberos 5 system the ID of
  79 the "IMAP Superuser".  This userid is used by the web server to log
  80 into the UW IMAP server via SASL proxy authentication.  That is, to
  81 establish an IMAP session, the web server logs into the IMAP server
  82 via Kerberos as the IMAP Superuser (which must be configured on the
  83 IMAP server separately) and specifies in that SASL exchange that login
  84 in being performed on behalf of the UW Pubcookie-provided userid.
  85
  86 With the IMAP Superuser ID established and configured on the IMAP
  87 server, you'll need to acquire a Kerbero ticket on the web server.
  88 Typically, you'll want to install a crontab entry to periodically
  89 refresh the ticket.  See web/src/pubcookie/README.
  90