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