Editing Add a parallel authentication routine (section)

==Editing the registration system to authenticate==
===Task 1: registration===
We need to edit <code>cgi/register</code>:
* We need to add "auth_service" to the <code>@sysfields</code> array.
<pre>
	my @sysfields;
	unless( $min )
	{
		@sysfields = ( "username", "email", "newpassword", "auth_service" );
	}
	else
	{
		@sysfields = ( "email", "newpassword" );
	}

</pre>
'''NOTE''' Simply by adding <code>auth_service</code> to the end of the <code>@sysfields</code> list, it will be displayed in the registration form, using the phrases defined in <code><archives/''ARCHIVEID''/cfg/lang/en/phrases/user_fields.xml/code> (see below)

* Between the ''do we have the required fields'' section and the ''does the email exist'' section, we add our authentication check:
<pre>
  # Which authentication service to use?
  $_ = $v->{auth_service};
  my $authorise;
  my $uid;
  my $inst;

AUTHO_TYPE:
{  
  /athens/ && do
  { 
    $authorise = EPrints::YourOrg::Autho::athens_autho($session);
    
    unless ($authorise)
    {
     	return mk_err_page( 
        $session,
        "cgi/register:failed_athens", 
        $fieldlist,
        $v,
      );
    }
    $puid  = $authorise->{'userID'};
    $inst  = $authorise->{'institution'};  
    last AUTHO_TYPE;
  }; 
  /shibboleth/ && do
 {
    $authorise = EPrints::YourOrg::Autho::shibb_autho($session);
    unless ( $authorise )
    {
        return mk_err_page( 
          $session,
          "cgi/register:no_shibb", 
          $fieldlist,
          $v,
        );
    }
    $puid  = $authorise->{'userID'};
    $inst  = $authorise->{'institution'};  
    last AUTHO_TYPE;
  };
  /ldap/ && do 
  {
    $authorise = EPrints::YourOrg::Autho::ldap_autho($session);
    unless ( $authorise )
    {
        return mk_err_page( 
          $session,
          "cgi/register:no_ldap", 
          $fieldlist,
          $v,
        );
    }
    $puid  = $authorise->{'userID'};
    $inst  = $authorise->{'institution'};  
    last AUTHO_TYPE;
  }; 
} ## end of AUTHO_TYPE switch


  # has the puid already been registered
  if( defined EPrints::DataObj::User::user_with_puid( $session, $puid ) )
  {
    return mk_err_page( 
      $session,
      "cgi/register:puid_exists", 
      $fieldlist,
      $v,
      {email=>$session->make_text( $puid )}
    );
  }
</pre>

The core information in this code is
* that there is a parameter called <code>auth_service</code>, which is used to indicate with external authentication system was used,
* that each authentication method returns a reference to a hash,
* the returned hash contains the PUID (and could contain other information),
* each authentication method has an associated error message
* that we need to check that the PUID has not been used with another account.

Having got an acceptable set of details for the new user, we need to add the new details to the user object.. so just before we create the user object, there is a bit more code (insert just before <code>my $user_dataset = $session->get_repository->get_dataset( "user" );</code>:
<pre>

  $user_data->{puid} = $puid;
  
  # has the puid already been registered
	if( ! $inst )
	{
		return mk_err_page( 
			$session,
			"cgi/register:no_inst", 
			$fieldlist,
			$v,
			{email=>$session->make_text( $inst )} );
	}
  $user_data->{org} = $inst;

  # OPTIONAL: Log the new user, and how they authenticated
  $session->get_repository->log( "Registering user (".$user_data->{username}. ") with puid [". $user_data->{puid}."]" );

  # Insert code above here
  my $user_dataset = $session->get_repository->get_dataset( "user" );

</pre>

and lastly, in <code>sub make_reg_form</code>, we need to define the default option from the <code>auth_service</code> set:
<pre>
	$defaults->{auth_service} = 'shibboleth';
</pre>

===Authentication routines===
The various authentication routines (<code>EPrints::YourOrg::Autho::*</code>) could live anywhere, however I suggest that you keep them in an area specific to your organisation. In Perl-parlance, <code>EPrints::YourOrg::Autho::foo</code> means the subroutine ''<code>foo</code>'' in the perl package ''<code>Autho.pm</code>'', in the directory ''<code>EPrints/YourOrg/</code>'' (<code>or perl_lib/EPrints/YourOrg/Autho.pm</code> for an eprints install)

How the individual routines work is very dependant on your local environment, however this is how I have done my [[Shibboleth authentication]], using the UK Access management Federation

===Phrases===
There are a number of new ''phrases'' used in this routine. They will all need to be added to <code><archives/''ARCHIVEID''/cfg/lang/en/phrases/system.xml/code> - e.g.
<pre>
    <epp:phrase id="cgi/register:failed_athens"><p>Athens Authentication failed.</p></epp:phrase>
    <epp:phrase id="cgi/register:no_shibb"><p>UK Access Management Federation Authentication failed.</p></epp:phrase>
    <epp:phrase id="cgi/register:puid_exists"><p>When you registered you were bounced through an external <em>authenticating</em> portal. A user exists that has the same <em>Persistent User ID</em> as the one you have given.</p><p>Please <a href="reset_password">reset your password</a>.</p></epp:phrase>
    <epp:phrase id="cgi/register:no_inst"><p>Unable to determine the organisation used to authenticate you. Please contact xXx for help.</p></epp:phrase>
</pre>
and <code><archives/''ARCHIVEID''/cfg/lang/en/phrases/user_fields.xml/code> - e.g.
<pre>
<epp:phrase id="register_fieldopt_auth_service_athens">Athens Authentication Service </epp:phrase>
<epp:phrase id="register_fieldopt_auth_service_shibboleth">The UK Access Management Federation</epp:phrase>
<epp:phrase id="register_fieldopt_auth_service_ldap">Poppleton University's EaSY Sign-on System</epp:phrase>
</pre>

===Finding a user via PUID===
We need to confirm that the PUID is not in use. Essentially we replicate the ''user_with_email'' and ''user_with_username'' routines.
We create this new routine in <code>archives/''ARCHIVEID''/cfg/cfg.d/myCode.pl</code> so than we don't lose it if we upgrade the EPrints code-base.
(note how we define the routine as being in a specific package...)
<pre>
######################################################################
=pod

=item $user = EPrints::DataObj::User::user_with_puid( $session, $puid )

Return the EPrints::user with the specified $puid, or undef if they
are not found.

=cut
######################################################################
sub EPrints::DataObj::User::user_with_puid
{
	my( $session, $puid ) = @_;
	
	my $user_ds = $session->get_repository->get_dataset( "user" );

	my $searchexp = new EPrints::Search(
		session=>$session,
		dataset=>$user_ds );

	$searchexp->add_field(
		$user_ds->get_field( "puid" ),
		$puid );

	my $searchid = $searchexp->perform_search;
	my @records = $searchexp->get_records(0,1);
	$searchexp->dispose();
	
	return $records[0];
}
</pre>