GWSSO - GroupWise single-sign-on capability

This hack implements a single-sign-on capability for GroupWise WebAccess that works with the Luminis portal.

Download: gwsso-0.3.zip

Now updated for GroupWise 8! If you are still on GroupWise 7, use gwsso-0.2.zip.

============
How it Works
============

Three entities are involved...

    * the user's PC, running a supported web browser, called the Client
    * the portal server, i.e. Luminis, called the Connector
    * the application, i.e. GroupWise, called the Application

This is how a typical single-sign-on (SSO) works...

    * The Client asks the Connector to be logged into the Application.
    * The Connector performs a login by transmitting the user's
      credentials to the Application, and receiving a cookie from the
      Application representing that user's session.
    * The Connector gives that cookie to the Client in the form of a
      pickup.html redirect.
    * The Client connects to the pickup.html page, which sets the
      session cookie then redirects to the application's main page.

The problem with GroupWise WebAccess is that it keeps the "session id"
in the URL, which the Luminis-style SSO is not capable of handling.

The solution presented here consists of two helper scripts, written
in Perl. The first helper script receives the user's credentials from
Luminis and generates a cookie that the user can use to get access
to the application. This cookie is passed to the user through the
pickup.html page. The user then provides that cookie the second helper
script, which performs the actual login to GroupWise using the
saved credentials.

This is an outline of what happens...

    * The Client asks the Connector to be logged into the Application.
    * The Connector transmits the user's credentials to Application,
      performing a logon.
          o In this case, Luminis POSTs the GroupWise credentials
            to the "sso_login" helper script (part of this package) at
            https://webaccess.example.org/cgi-bin/sso_login. 
          o sso_login encrypts the credentials and stores the encrypted
            credentials in a cookie, which is given to Luminis.
    * The Connector gives the Client the cookie using a redirect
      through http://webaccess.example.org/pickup.html.
    * The Client connects to the pickup.html page, which sets the
      session cookie, then redirects to the second helper script,
      webacc-helper.cgi.
          o webacc-helper.cgi decrypts the credentials stored in the
            cookie, performs the actual GroupWise login, then redirects
            the Client to the GroupWise main page

========================
How to Configure Luminis
========================

I'm not a Luminis guy, so I'm pretty fuzzy on the details here.
The basic idea is this:

  Luminis POSTs the credentials to the sso_login helper script,
      https://webaccess.example.org/cgi-bin/sso_login
  Luminis takes the cookie it gets back, and redirects the user,
  through a pickup.html page, to 
      https://mymail.messiah.edu/gw/webacc?merge=webacc&User.interface=css

sso_login is easy enough to understand. It takes the credentials,
encrypts them, and returns them in the form of a cookie. Which Luminis
can understand.

That final URL is a little tricker. Thanks to some Apache configuration
magic, that URL is actually mapping to the webacc-helper.cgi script.
In fact, any webacc url that has a merge= argument but not a context=
argument, will go through the webacc-helper.cgi script. The
webacc-helper.cgi script looks for the cookie that sso_login generated,
and if found, will perform a login to GroupWise webaccess, take the
sessionid that GroupWise provides, and add that to the URL.

==========
Installing
==========

Procedure for enabling single-sign-on on SLES 10.

   1. Install SuSE Linux Enterprise Server 10, and GroupWise 8:
          * WebAccess agent
          * WebAccess application with Apache and Tomcat

   2. Configure WebAccess application:
          * Uncheck Use client IP in securing sessions
          * [skip] Uncheck Use cookies

   3. Install these RPM packages:
          * gcc
          * openssl-devel
          * perl-IO-Socket-SSL
          * perl-Net_SSLeay 

   4. Install these CPAN modules:
          * Crypt::Blowfish
          * Crypt::CBC
          * CGI::Session
          * LWP::UserAgent 
        FYI- to install a CPAN module, run (as root)
            perl -MCPAN -e 'install "MODULE"'
          where MODULE is the name of the module to install

   5. Install the following file to /srv/www/htdocs:
          * pickup.html

   6. Install the following files in /srv/www/cgi-bin:
          * sso_login
          * webacc-helper.cgi

   7. Check both of these files for configuration variables. Near the
      top of each file are URLs and hostnames that will need to be
      modified for your site.

   8. In particular, the @KEY_BYTES variable should be customized for
      your site. In a site using load-balancing for GroupWise, you will
      need to configure the same set of random numbers on all servers.
      In addition, both files (sso_login and webacc-helper.cgi) should
      have an identical set of numbers.

   9. Edit /etc/sysconfig/apache2:
          look for, and add if it is missing, these two modules in the
          APACHE_MODULES list:
             cgi
             rewrite

   10. Edit /etc/apache2/vhosts.d/vhost.conf. Insert the
       following before the first <Directory> directive.

            RewriteEngine On
            # if user.context is specified, stop rewriting
            RewriteCond %{QUERY_STRING} User\.context=
            RewriteRule ^/gw/webacc$  - [L]

            # otherwise, pass to the CGI helper
            RewriteCond %{QUERY_STRING} merge=
            RewriteRule ^/gw/webacc$ /cgi-bin/webacc-helper.cgi [L,PT]

   11. Edit /etc/apache2/vhosts.d/vhost-ssl.conf. Repeat the same
       edit as for vhost.conf.

   12. /etc/init.d/apache2 restart 

Last updated: 2009-07-29