How do I run my own Bluestem server?

In such a case, if you are running your own web server (i.e. physically secure room, maintain security patches, manage user accounts, run backups, install and troubleshoot software, keep and inspect logs), you can make your web server into a Bluestem Application Server. This will allow your web scripts to authenticate users, using their normal Bluestem NetID and password, in a very secure manner.

Requirements

• You must run an SSL-capable web server. Apache and IIS are fine. And, of course, the web server must be configured to run CGI scripts.
• You must obtain an SSL certificate.
• You must install perl.
• You must maintain a correct clock setting on your server. Use something like NTP, so that your server and the Technology Solutions bluestem ID servers do not have any significant clock skew.
• It should go without saying, you must be able to maintain your server, providing all the functions that a good sysadmin would provide.

You have to run perl, but you don't have to write it. You can make bluestem calls from ASP, using thelittle bluestem protocol. And if needed, you can probably adapt this to other languages as well.

Security Consideration

One of the main features of Bluestem is that the user's password is never sent to the application server, not even encrypted or used as an encryption key. So it's not possible for a rogue application server to compromise a user's password.

However, all bluestem applications on a given server need write access to the internal bluestem cache. Suppose you have two developers writing web scripts (with or without bluestem) for your server. Each of them has access to the bluestem cache, because their scripts run with the identity of the web server. This means that Developer A can poison the bluestem cache, and therefore can impersonate Person X to any bluestem application on your server. He can't affect bluestem applications on other servers like tigger, but he can certain affect all applications on your server.

Moral of Story: don't let just anyone write CGI scripts on your server.

You may wonder how we allow normal users on tigger or icarus to use bluestem with their own CGI safely. The answer is that we insist on using a modified version of Cgiwrap. Cgiwrap launches as root, runs the bluestem code, puts the authenticated NetID into the environment, then changes uid to the user and exec's the user's script. The point is, by the time the user's code runs, it no longer has read or write access to the bluestem cache, so all is well.

Registering your Application Server

Application servers are registered at the following URL:

https://login.uic.edu/bluestem/admin?opt=aservers

If your NetID isn't yet configured as an application server administrator then you'll get a permission denied message. To request your NetID be registered as an application server administrator, please contact singlesignon@uic.edu.

If your NetID is already configured as an application server administrator then you will be presented with a screen you can use to define your Bluestem application server and generate your application server key. When you add your application server you will need to set:

Hostname

This is the hostname of your application as to be used in a client's browser when they access your site. So if your site is accessed as "https://mysite.mydept.uic.edu/" then you should specify the hostname as "mysite.mydept.uic.edu". This may or may not be the same as the registered hostname for your server depending on your configuration. If you have multiple load-balanced servers all serving the same site then you should just register once with the public hostname of your application and have all servers use the same server key.

Description

This is the name of your application, it should just be a few words to describe the application such as: "Some department intranet server."

Server Key

A random server key is automatically generated for you. If you wish to copy over an existing server key, just copy and paste it into the Server Key input field. You'll need your server key during the installation, so you may want to copy and paste it into a text editor.

Installation

UIC's bluestem client software is available from the application server administration page mentioned above or from the following URL:

https://login.uic.edu/pub/

The steps to setup a Bluestem application server are given in brief below. For more detailed instructions please see the README file included in the Bluestem client download.

1. Register your application server as described above. Contact singlesignon@uic.edu if you need your account configured as a Bluestem administrator.
2. Set up your web server, and get an SSL certificate. The SSL cert should specify the same hostname registered as an application server as described above. You may want to get a special DNS CNAME for this purpose, so you can later move your bluestem server and cert to a different machine without hassle.
3. Unzip or untar the library as appropriate and run install.pl. You will be prompted to provide serveral options. For most of these we recommend selecting the defaults but you will at least need to specify the hostname and server key created when you registered your application server.
4. Next you'll need to configure your webserver for bluestem. For Microsoft IIS this means creating virtual directory from the web paths specified for CGI and images to the folders these were saved to. For Apache httpd, you'll need a ScriptAlias and an Alias directive to do the same thing. For Apache httpd we include a file bluestem.httpd.conf that can be used with an Include directive from your apache httpd configuration file.
5. Test it. The first test your should look at is admin.cgi (admin.pl on IIS). This script will perform some sanity checks like making sure all required perl modules are available and the cache directory is writable. You'll need your server key to use this program. If that looks good, attempt to authenticate with test.cgi (test.pl on IIS). If you get an error about SSL, then you need to install the perl module Net::SSLeay or Crypt::SSLeay. For help with your installation, please contact singlesignon@uic.edu

Securing a Site with Apache httpd authentication

In bluestem.httpd.conf there are two examples of configuring Apache httpd to force Bluestem authentication. Both require your webserver have mod_perl installed. To use these authentication methods, uncomment the line:

PerlRequire /usr/local/bluestem-client/startup.pl

This causes mod_perl to preload the Apache::Bluestem libraries used to perfrom Bluestem authentication.

Now you can implement either an access handler or an authentication handler. Either of these can be specified for a <Directory> or <Location> directive.

The access handler implements the allowed.netids access control as described at How do I restrict access to web pages with Bluestem? The access handler can be enabled as follows:

PerlAccessHandler Apache::Bluestem::access_handler

The authentication handler forces all users accessing the specified resource to authenticate with Bluestem then checks their NetID against and "require user [NetID] ..." statements, or just "require valid-user" to permit anyone with a valid NetID. For example:

<Location "/restricted-path">
    AuthName Bluestem
    AuthType Bluestem
    PerlAuthenHandler Apache::Bluestem::authen_handler
    require valid-user
</Location>

Using Little Bluestem

The Little Bluestem protocol defines a simple method for checking if a user is authenticated and looking up their NetID. This consists of:

1. Read the Bluestem cookie. The cookie name should be: Bluestem_HOSTNAME and the value is the cache ID joined to a cache key joined with a tilde.
2. Read the cache file for the cache ID from the cookie. The cache format is: NETID,IP,KEY,ID_SERVER. (Note the NetID does not contain '@uic.edu' if the user is from UIC). Check the cache key from the user's cookie against the KEY from the cache.
3. If the cacheid isn't found, the age of the cache is too old or the NetID is "Unknown" then redirect the user to lb_login.cgi (or lb_login.pl on windows).

There are several implementations of the Little Bluestem protocol already written. An implementation of Little Bluestem an classic ASP is included with the Bluestem Client for windows. For an example of using the Little Bluestem with ASP see bluetest.asp, included with the windows Bluestem Client distribution.

Using Bluestem in your own Perl Scripts

It is sometimes helpful to write your own Perl scripts that can use the Bluestem libraries. Examples of how to do this can be found in the test.cgi and test1.cgi scripts provided with the Bluestem client.

Using the object oriented interface shown in test.cgi:

#!/usr/bin/perl
use strict;
use warnings;

# Customize to your installation directory.
use lib "/usr/local/bluestem-client/lib";
use Bluestem::CGIClient ();
my $cgi = CGI->new();
my $bsc = Bluestem::CGIClient->new(
   cgi => $cgi,
);
my $session = $bsc->get_session();
unless( $session ) {
   $bsc->handle_login();
   exit 0;
}
my $ID = $session->{NetID};

# ID is known.  Carry on.
...

If using the old interface as shown in test1.cgi be sure to note that bluestem.pl is no longer supported. If your programs begin with "require 'bluestem.pl';" then you will need to change it to "use Bluestem;" as shown below.

#!/usr/bin/perl
use strict;
use warnings;

# Customize to your installation directory.
use lib "/usr/local/bluestem-client/lib";
use Bluestem ();

# check for bluestem ID
my($ID, $IdleTime, $SessionTime) = bluestem_id();

# If no ID, force login
bluestem_login unless $ID;

# ID is known.  Carry on.
...

Note: Bluestem provides an authenticated NetID. Period. It does not tell you if the person is staff or student, it does not tell you what department they are in, it does not tell you what privileges they have. Just the NetID. It is up to your script to decide what privileges to allow the person, based on the NetID.

About Bluestem IDs

A Bluestem ID has three parts, and can look like this: adabyron@uic.edu/tacacs

The Bluestem Id usually has the defaults removed, so the above would simply be: adabyron. Note that the following could all represent different people:

• adabyron
• adabyron@uiuc.edu
• adabyron/kerberos
• adabyron@uis.edu/tacacs

Troubleshooting

• Check your log file.
• Do non-bluestem CGI scripts run ok on your server? Do they run correctly from the Bluestem CGI directory? If this doesn't work, nothing else will.
• Your webserver runs as some identity. (On unix, this is often the nobody account.) Make sure this user has write access to the bluestem cache and to the bluestem log file. And be sure that only trusted accounts have read or write access to this cache.
• Check your system clock. If you are out of sync with the bluestem ID servers, bluestem can't properly calculate cache ages. If the clocks are skewed by 5 minutes, bluestem will fail. Use NTP to keep this adjusted.
• You did check your log file, didn't you?
• If you still need assistance, send the following information to singlesignon@uic.edu:
  • Name of your server
  • Description of the problem, including a url where we can verify the problem
  • Small relevant selection from the log file (just cut-and-paste a few lines, don't attach the whole thing).