Shibboleth authentication

Shibboleth Authentication

TIMTOWTDI (There Is More That One Way To Do It)

This is the system I implemented for using with the UK Access management Federation (which is a Shibboleth implimentation).

How Shibboleth Works

The UK-AMF authentication is reasonably complicated:

The user is directed to a Shibboleth authentication point, supplying a Context URL.
Once the user has been authenticated, the Context URL is called.
The Context URL processes the data from the authentication point and returns a URL with an initiated session (however (if!) the web site uses session management)
The user's browser is redirected to that URL (effectively by their own browser)

How to make EPrints do this

There are two problems when implimenting this under EPrints:

EPrints does it's session management in a cookie not via a URL parameter
- It is desirable to leave as much of that session management as standard as possible.
The user Authentication (and Identification) and the actual Login process are done in different places, with multiple HTTP page calls.
- Passing user identification details as parameters in an insecure http request means that someone can fake authenticated credentials and thus get access when they shouldn't.

What I have implemented is something similar to the standard eprints login_ticket system: the context URL phase sets some entries in an authorisation table, and then the main EPrints code just pulls the identity parameters from the table.

Adding a table to the database

In perl_lib/EPrints/Database.pm add the following code: In sub create_archive_tables, add

	$success = $success && $self->create_auth_tickets_table();

and then add the following two mathods

# $db->create_auth_tickets_table()
# 
# create the auth_tickets table.

sub create_auth_tickets_table
{
  my( $self ) = @_;

  my $sql = "CREATE TABLE auth_tickets ( code CHAR(32) NOT NULL, puid VARCHAR(255), orgid VARCHAR(64), expires INTEGER, primary key( code ) )";

  return $self->do( $sql );
}

# $db->get_auth_puid( $code )
# 
# return the puid, if any, associated with the given auth ticket code.

sub get_auth_puid
{
  my( $self, $code ) = @_;

  my $sql;

  # clean up old tickets
  $sql = "DELETE FROM auth_tickets WHERE ".time." > expires";
  $self->do( $sql );

  $sql = "SELECT puid,orgid FROM auth_tickets WHERE code='".prep_value($code)."'";
  my $sth = $self->prepare( $sql );
  $self->execute( $sth , $sql );
  my( $puid, $orgid ) = $sth->fetchrow_array;
  $sth->finish;

  return ($puid, $orgid);
}

The Authentication routine

I have all my authentication routines in the same place (perl_lib/EPrints/myCode/Autho.pm) which makes it available in multiple places.

The Shibboleth routine is:

sub shibb_autho {
   my ($session) = @_;
   
   my $authentication_point = 'https://Your.Shibb.Authentication.Point/with/path';
   my $secret_code;
   my $orgName;
   my $puid;
   
   if (! $session->have_parameters)
   {
     my $args = $session->{'request'}->args();
     $args =~ /s=(.*?)[&;\b]/;
     $secret_code = $1; # $r->param('session');
   }
   else {
     $secret_code = $session->param('s');
    }
   my $ath_returl = $session->get_full_url;
   
   unless ($secret_code)
   {
    redirect(
              url => '$authentication_point',
              params => {
                context => $ath_returl,
                service => 'myServiceCode',
              }
            );
    exit; 
  }

  ($puid, $orgName) = $session->{database}->get_auth_puid( $secret_code );  
  
  return unless $puid;
  
  my %return_hash = (
                      userID     => $puid,
                      orgName    => $orgName,
                    );
 
  return \%return_hash;
}

Looking at the code, it breaks down into two main parts:

If there is no secret code then we assume the user has not been via the authentication point, and send them there
If we have a secret code then we use it as the index for the authentication table, and pull out the puid.
- if we don't get a puid, return (as a failure)
- if we have got a puid, build a return-hash and send it back.

The context URL

The script for reading the authentication details needs to be within the EPrints server, and ideally protected by a secure (https) connection.

The actual code is very simple: get the EPrints session code from the EPpints cookie, and use that as the index for the data supplied by the Shibboleth authentication server.

use EPrints;

use strict;

my $context;
my $puid;
my $orgid;
my $uri;

my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );

my $code = EPrints::Apache::AnApache::cookie( $self->get_request, "eprints_session" );

if ( EPrints::Utils::is_set( $code ) )
{

  $context    = $session->param('context');
  $puid       = $session->param('id'  );
  $orgid      = $session->param('rorg');
  
  my $sql = "REPLACE INTO auth_tickets VALUES( '".
            EPrints::Database::prep_value($code). # the ticket-code
            "', '".
            EPrints::Database::prep_value($puid)  # puid
            "', '".
            EPrints::Database::prep_value($orgid) # orgid
            "', ".
            (time+60*5).                          # expire-time (5 minutes from now)
            " )";
  my $sth = $self->{database}->do( $sql );
  
  $uri = "$context&s=$code";
} else {
  $uri = $session->get_repository->get_conf( "base_url" )."cgi/register"
}

print "$uri\n";
exit;

As an extra precaution, it may be advisable to have an extra $ENV{'REMOTE_ADDR'} =~ /111.222.333.444/ && in the if expression - to restrict access to just the Shibb server (there is no such thing as too much security in these things.)

Using the code

Using the code is now pretty easy:

    $authorise = EPrints::myCode::Autho::shibb_autho($session);
    unless ( $authorise )
    {
        return mk_err_page( 
          $session,
          "cgi/register:no_shibb", 
          $fieldlist,
          $v,
        );
     }
     
     $v->{puid} = $authorise->{'edinaUserID'};
     $orgid = $authorise->{'organisationNum'};

Shibboleth authentication

Contents