Add a parallel authentication routine

This is a real-world example.

goal

Use an external agency that may define a persistent User ID (a "puid") for someone visiting the repository.

explanation

An eprints user may have an identifying puid assocciated with their account. If a user arrives with a piud that matches one held in the tables, that user profile is loaded. If not, use the standard eprints login system is used to identify the user.

There are situations where a user may come in with a different puid (visiting a different institution, moving to a different institution, a change at institutional level, etc), and a user should be able to change the puid associated with their account.

Note: puids are opaque, so humans do not recognise the opaque string as meaning anything, and asking a user to type in a puid is prone to typo-errors. However, puids are assigned by an institution, so I made sure I got the name of the institution that authenticated the user along with the puid.

Step 1

Step 1 is to set up the basic requirement: We need fields in the user object (archives/ARCHIVEID/cfg/cfg.d/user_fields.pl)

   {
        'name' => 'puid',
        'type' => 'text',
    },
    {
        'name' => 'puid_inst',
        'type' => 'text',
    },

and the corresponding entries in the workflow and phrases files: Workflows (archives/ARCHIVEID/cfg/workflows/user/default.xml)

    <component type="Field::Multi">
      <title><epc:phrase ref="user_section_account" /></title>
      <epc:if test="usertype != 'minuser'"><field ref="email"/></epc:if>
      <field ref="hideemail"/>
      <field ref="password"/>
      <field ref="puid" /> <!-- NEW ITEM -->
      </component>

phrases (archives/ARCHIVEID/cfg/lang/en/phrases/user_fields.xml):

    <epp:phrase id="user_fieldname_puid">Devolved Authentication</epp:phrase>
    <epp:phrase id="user_fieldhelp_puid">This option determines which (if any)
                   institution is recognised as providing the correct devolved
                   authentication for this depositor.</epp:phrase>

NOTE If you alter the user_fields.pl file, you need to rebuild the database, which means wiping and restarting (or doing clever stuff with SQL), so make sure you do all this before you start putting data into the repository

There is a Problem

However, this means that we get a text input item, not what we want (see the comment above about users typing in opaque strings)

Step 2

In Step 2 we alter the way the object deals with the 'puid' field. the user field is changed and we define alternative methods for rendering the field (as a fragment of xhtml) and for changing the value:

    {
        'name'                => 'puid',
        'type'                => 'text',
        'render_single_value' => \&render_puid,
        'render_input'        => \&select_puid,
    },

In archives/ARCHIVEID/cfg/cfg.d/user_fields.pl we also add the two methods:

sub render_puid {
    my ( $session, $field, $value ) = @_;
    my $inst;
    if ($value) {
        $inst = $session->{current_user}->get_value('puid_inst'); 
        return $session->make_text(
            "Your defined authenticating institution is <strong>$inst</strong>")
          if ($inst);
        return $session->make_text(
            "You have an inatitution defined, but it is un-named");
    }
    else {
        return $session->make_text("You have no automatic authentication");
    }
}

sub select_puid {
    my ( $field, $session, $puid, $dataset, $staff, $hidden_fields, $user,
        $basename ) = @_;

    my $c = $session->{request}->connection;
    my $inst = $user->get_value('puid_inst');
    my $this_puid = $c->notes->get('this_puid');
    my $this_inst = $c->notes->get($this_puid);
    unless ($puid) {
        if ($this_puid) {
            my $fragment = $session->make_doc_fragment;
            $fragment->appendChild(
                $session->make_text(
                    "You may change your authenticating institution:")
            );
            my $element =
              $session->make_element( "select", name => $field->get_name );
            $element->appendChild(
                $session->render_single_option( "", "None", 1 ) );
            $element->appendChild(
                $session->render_single_option(
                    $this_puid, $this_inst, 0
                )
            );

            $fragment->appendChild($element);
            return $fragment;
        } ## end of $this_puid
        else {
          return ( $session->make_doc_fragment("You have nothing defined") );
        }
    }
    else {
        if ( $this_puid && ( $this_puid ne $puid ) ) {
            my $fragment = $session->make_doc_fragment;

            $fragment->appendChild(
                $session->make_text(
                    "You may change your authenticating institution:")
            );
            my $element =
            $session->make_element( "select", name => "id3_".$field->get_name );
            $element->appendChild(
                $session->render_single_option( "", "None", 0 ) );
            $element->appendChild(
                $session->render_single_option(
                    "$puid", $user->get_value('puid_inst'), 1
                )
            );
            $element->appendChild(
                $session->render_single_option(
                    $this_puid, $this_inst, 0
                )
            );
            $fragment->appendChild($element);
            return $fragment;
        }
        else {
            return render_puid( $session, $field, $puid );
        } ## end of $puid eq $this_puid
    } ## end of unless ($puid) {} else...
}

This works well, however there is a small snag - how are we setting $c->notes->get('this_puid');?

Well, this is all done in perl_lib/EPrints/Session.pm, specifically in _current_user_auth_cookie:

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

	if( !defined $self->{request} )
	{
		# not a cgi script.
		return undef;
	}

  # Hack to ensure that the Repository Junction details are set before
  # the local EP3 cookie stuff takes over
  my %cookie;
  my ($puid, $orgname);
  
	# we won't have the cookie for the page after login.
	my $c = $self->{request}->connection;

  unless ( $c->notes->get( "this_puid" ) ) {
    warn "Not got RJunction cookie";
    my $rj_cookie = EPrints::Apache::AnApache::cookie(  $self->get_request, "depot_authen" );

    if( defined $rj_cookie ) {
      %cookie = split /&/, $rj_cookie;
      ## Do clever stuff to extract $puid and $orgname from the cookie ##
      $c->notes->set( "this_puid", $puid );
      $c->notes->set( $puid, $orgname );
    } ## end of cookie defined
  } ## end of "if note set"
  ## end of first bit of hack, back to normal, but the coding is slightly altered

  my $userid = $c->notes->get( "userid" );
  $c->notes->set( "userid", 'undef' );

  my $user;
  
  # Check for a userid set in the session notes area
  if( EPrints::Utils::is_set( $userid ) && $userid ne 'undef' )
  {	
    $user = EPrints::DataObj::User->new( $self, $userid );
  }
  
  # if not, check for an EPrints user session cookie
  unless ( $user ) {
    my $cookie = EPrints::Apache::AnApache::cookie( $self->get_request, "eprints_session" );
    if ( $cookie  ) {
      my $remote_addr = $c->get_remote_host;
      $userid = $self->{database}->get_ticket_userid( $cookie, $remote_addr );
      $user = EPrints::DataObj::User->new( $self, $userid ) if EPrints::Utils::is_set( $userid );
    }
  } 

  # If still not, can we authenticate with a puid?
  unless ( $user ) {
    if ( $c->notes->get( "this_puid" ) ) {
      $user = EPrints::DataObj::User::user_with_puid( $self, $c->notes->get( "this_puid" ) );
    }
  }
 
  # if we get a user, by hook or by crook, set some details in the notes section
  if ( $user ) {
    if ( $user->get_value('puid') ) {
      $c->notes->set( 'puid' , $user->get_value('puid' ) );
      $c->notes->set( $user->get_value('puid') ,
                      $user->get_value('puid_inst') );
    }
    return $user;
  }
  
  # if we really cannot find a user, return undef (no user found)
  return undef;
}

and the method for dealing with the returned item.

sub fromform_puid {
    my ( $value, $session ) = @_;
    
    warn "\n\nUsing fromform to set value >$value<\n";

    my $c = $session->{request}->connection;
    my $inst = $c->notes->get($value);
    my $user = $session->current_user;

    $user->set_value('puid_inst', $inst );
    $user->commit;
    warn "\n\n... Returning >$value< and set puid_inst >".$user->get_value('puid_inst')."< for user ".$user->get_value('userid');

    return $value;
    
}

Session.pm is mightily hacked,