SSO on www.mathcs HOWTO

Table of Contents

  1. What SSO Does
  2. What SSO Doesn't Do
  3. Getting a SiteID
  4. Setting Up Your .htaccess File
  5. Testing SSO
  6. Using SSO for User Preferences

What SSO Does

Bethel's Single Sign On (SSO) server allows members of the Bethel Community that have websites on a Bethel webserver to restrict access to other members of the Bethel Community with secure authentication. Also, if a user is already logged into another Bethel website that also uses the SSO server for authentication, the user will not need to enter their username and password again.

A session will time out after a length of idle time (defaults to 60 minutes but can be changed on request) or once the browser is closed.

Sites that are not official Bethel sites (such as student pages on www.mathcs) will display to their users a warning page on the first visit that lets the user know that the following site is not an official Bethel website and that the site's owner does not have the ability to access any of that user's personal information including passwords but only the ability to authenticate them.

SSO allows the website's owner to restrict the site to all members of the Bethel Community that have a Bethel Community Account (BCA) or a list of specific BCAs. You can also allow all requests from a specified range of IPs without requiring users to log in. In this case only requests from IPs outside this range will require users to log in.

What SSO Doesn't Do

SSO does not allow people without BCAs to log in to a site, unless the site has specified a range of IPs that don't need user authentication.
SSO is only known to work on apache/mod_perl running on various flavors of unix-like OSes.

Getting a SiteID

The first thing that needs to occur to use Bethel's SSO server is to request a SiteID for your site on www.mathcs. To do this visit http://incidentbase.its.bethel.edu/useraccess/ and click "Create Incident." Enter "Requesting SSO SiteID for www.mathcs" in the Brief Description field. In the full description enter the URL you want associated with the SiteID. This URL will look similar to http://www.mathcs.bethel.edu/~schdav/. Note the trailing '/' character: this is necessary for SSO to work properly and will need to be included in all links to your site. Submit the incident and ITS will contact you with your SiteID.

Setting Up Your .htaccess File

To restrict access to your site, you need to set up a file called '.htaccess' in your public_html directory on shell.mathcs.bethel.edu. This file will look similar to the following:

   PerlAccessHandler BethelAuth
   PerlSetVar SiteID 1
   PerlSetVar NoShowUsername 1
   PerlSetVar CookiePath /mysite
   PerlSetVar AllowIP 140.88
   PerlSetVar users username1,username2

The first line tells apache to use the perl module "BethelAuth" for authentication. The second line is where you would put your SiteID. The third line is optional. By default you are given the ability to access the user's username with scripts (stored in the REMOTE_USER cgi environment variable), but if you set this variable to 1 as shown above this functionality is disabled. The fourth line is imperitive for sites on www.mathcs.bethel.edu and should be set to a slash, a tilde and your username (like '/~schdav'). If you do not set this variable your SiteID will probably get disabled. The fifth line is optional and allows you to restrict access to any machine in a certain IP range. No login is then necessary unless the requesting IP is from outside this IP range. The sixth line allows you to restrict access to a comma seperated list of usernames.

Testing SSO

To test your SSO authentication setup, navigate to the site you set authentication up for (don't forget the trailing slash). You should be prompted for your username and login (unless you are already logged in to another SSO site) and then be warned that the site you are entering is not an official Bethel site. After that you will be taken to the requested site. If all goes as described, you're all setup!

Using SSO for User Preferences

A common use for SSO is to set up user preferences. Many web sites provide users with different content based on who that user is, and you may wish to do this with your www.mathcs site. SSO assigns the user's BCA username to the CGI environment variable REMOTE_USER, so all you would need to do in a perl CGI script is assign $ENV{'REMOTE_USER'} to a variable in your script and then use that variable to pull preferences from a storage mechanism like a file or a database (email david-schlenk@bethel.edu if you would like a mysql database on shell.mathcs).