Editing Shibboleth (section)

== Configuring Apache and EPrints ==
'''N.B. All these actions should be carried out by the ''eprints'' user, except when prepended with ''root>'' which means the command should be run as the ''root'' user.'''
* Add the following configuration to your archive's '''ssl/securevhost.conf''', after the '''Include /opt/eprints3/cfg/apache_ssl/foo.conf''', substituting '''foo''' for your archive's name where appropriate.  (This assumes you are running Apache 2.4 or greater).  See [[#Apache 2.2 (and lower) Configuration for EPrints Shibboleth Integration |Troubleshooting]] for instructions on the configuration to use for Apache 2.2. or lower.

 Alias /shibboleth /opt/eprints3/archives/foo/shibboleth
 <Location "/shibboleth">
   SetHandler perl-script
   PerlHandler ModPerl::Registry
   PerlSendHeader Off
   Options ExecCGI FollowSymLinks
 
   AuthType shibboleth
   ShibRequestSetting requireSession 1
   require shib-session
 </Location>
 
 <Location /cgi/shibboleth>
   AuthType shibboleth
   ShibRequestSetting requireSession 1
   require shib-session
 </Location>

* Copy the following code into your archive (e.g. /opt/eprints3/archives/foo/) as '''cgi/shibboleth'''.
 use EPrints;
 use strict;
 my $session = new EPrints::Session;
 exit( 0 ) unless( defined $session );
 
 $session->send_http_header( "content_type" => "text/html" );
 
 print "&lt;html&gt;&lt;head/&gt;&lt;body&gt;&lt;code&gt;\n";
 
 foreach my $key (sort keys(%ENV)) {
   print "&lt;p&gt;$key = $ENV{$key}&lt;/p&gt;";
 }
  
 print "&lt;/code&gt;&lt;/body&gt;&lt;/html&gt;";
 $session->terminate;
 exit;

* Now restart Shibboleth and Apache:
  root> systemctl restart shibd.service
  root> apachectl restart

* In a web browser go the '''/cgi/shibboleth''' page for your repository, (e.g. ''https://foo.eprints.org/cgi/shibboleth'').  You should be redirected to an error page for your your Shibboleth IdP (e.g. ''https://shib.foo.example.org/idp/profile/SAML2/Redirect/SSO?...'').  

* If instead you are displayed with a list of key values or are forbidden to access the page, you have not configured Apache properly, if so, see [[#Apache_Configuration_Issues|Apache_Configuration_Issues]] under [[#Troubleshooting|Troubleshooting]].  If you see an error message like the one below, you have not set up Shibboleth properly, if so, see [[#Shibboleth_Configuration_Issues|Shibboleth_Configuration_Issues]] under [[#Troubleshooting|Troubleshooting]].
 opensaml::saml2md::MetadataException
 The system encountered an error at Wed May 6 15:19:27 2015
 To report this problem, please contact the site administrator at root@localhost.
 Please include the following message in any email:
 opensaml::saml2md::MetadataException at (http://foo.eprints.org/cgi/shibboleth)
 Unable to locate metadata for identity provider (https://shib.foo.example.org/idp/shibboleth)

* Next, copy the following code into your archive (e.g. ''/opt/eprints3/archives/foo/'') as '''cfg/cfg.d/zz_shibboleth.pl'''.  This is needed to redirect login and logout to use Shibboleth rather than local login.
 $c->{get_login_url} = sub {
   my( $session, $target ) = @_;
 
   # preserve CGI params
   $session->read_params;
   $target = $session->get_url(
     host => 1,
     path => "auto",
     query => 1,
   );
 
   my $url = URI->new( $session->config( "https_url" )  . "/shibboleth/login" );
   $url->query_form( target => "$target" );
   return "$url";
 };
 
 $c->{on_logout} = sub {
   my( $session ) = @_;
   my $query = $session->query;
   return unless defined $query;
 
   # remove _shibsession_ cookie
   my( $shibname, $shibvalue );
   for( $query->cookie() ) {
     if( $_ =~ /^_shibsession/ ) {
       $shibname = $_;
       $shibvalue = $query->cookie( $shibname );
     }
   }
 
   my $cookie = $query->cookie(
     -name    => $shibname,
     -path    => "/",
     -value   => "",
     -host  => $session->config("cookie_domain"),
     -expires => "-1d",
   );
   EPrints::Apache::AnApache::header_out(
     $session->{request},
     "Set-Cookie" => $cookie 
   );
 };
 
 push @{$c->{rewrite_exceptions}}, "/shibboleth/";

* Create a folder at the top level of your archive (e.g. ''/opt/eprints3/archives/foo/'') called '''shibboleth''' and copy the main CSS file for Shibboleth into this folder:
 eprints> mkdir /opt/eprints3/archives/foo/shibboleth/
 eprints> cp /usr/share/shibboleth/main.css /opt/eprints3/archives/foo/shibboleth/

* Now, copy the following code into your archive (e.g. ''/opt/eprints3/archives/foo/'') as '''shibboleth/login'''.  This is the most basic login script that should work with the minimal attributes any Shibboleth IdP returns and '''only logging in users with existing accounts'''. Look under the [[#Customisation|Customisation]] section for advice on how to modify this script to meet your requirements, such as creation user accounts on-the-fly.
 use EPrints;
 use strict;
 
 my $session = EPrints::Session->new();
 my $url = $session->param( "target" );
 if ( defined $url )
 {
   my $target_uri = URI->new( $url );
   my $repository_uri = URI->new( $session->get_repository->get_conf( 'base_url' ) );
   if ( !$target_uri->can( 'host' ) || $target_uri->host ne $repository_uri->host )
   {
     $url = undef;
   }
 }
 $url = $session->get_repository->get_conf( "userhome" ) unless EPrints::Utils::is_set( $url );
 
 my $user = &get_user;
 
 if( defined $user )
 {
   $user->set_value( "last_login", EPrints::Time::get_iso_timestamp() );
   $user->commit;
 
   EPrints::DataObj::LoginTicket->expire_all( $session );
   $session->dataset( "loginticket" )->create_dataobj({
     userid => $user->id,
   })->set_cookies();
 }
 else
 {
   $url = $session->get_repository->get_conf( "base_url" ) . "/account_required.html";
 }
 
 $session->send_http_header( "content-type" => "text/html" );
 print '<html><head><meta http-equiv="refresh" content="0;url='.$url.'"/></head><body></body></html>';
 $session->terminate;
   
 sub get_user 
 {
   my ( $username, $email ) = ( undef, "" );
   if( $ENV{eppn} )
   {
    ( $username ) = split( /@/, $ENV{eppn}, 2);
    $username = lc( $username );
    $email = $ENV{eppn};
   }
   return unless EPrints::Utils::is_set( $username );
   my $user = $session->user_by_username( $username );
   if( defined $user && defined $email )
   {
     $user->set_value( "email", $email );
     $user->commit;
   }
   return $user;
 }

* Next, add the following markup to '''cfg/lang/en/static/account_required.xpage''' under your archive (e.g. ''/opt/eprints3/archives/foo/'').  Substituting ''staff and students of the University of Foo'' to describe to which particular group of people logged in access is restricted.

 <?xml version="1.0" standalone="no" ?>
 <!DOCTYPE page SYSTEM "entities.dtd" >
 <xpage:page xmlns="http://www.w3.org/1999/xhtml" xmlns:xpage="http://eprints.org/ep3/xpage" xmlns:epc="http://eprints.org/ep3/control">
 <xpage:title>Login Failed</xpage:title>
 <xpage:body>
    &lt;p style='text-align: center;'&gt;Please note that only staff and students of the University of Foo may log in to <epc:phrase ref="archive_name" />&lt;/p&gt;
 </xpage:body>
 </xpage:page>

* Now, reload Apache.
  root> apachectl reload

* In a web browser go to the '''/shibboleth/login''' page for your repository, (e.g. ''https://foo.eprints.org/shibboleth/login'').  Like before with ''/cgi/shibboleth'' you should be taken to your Shibboleth IdP's site albeit displaying an error message.

* The Shibboleth IdP shows an error message because EPrints as a Shibboleth Service Provider is not yet registered with it.  To do this you need to send the administrator of the Shibboleth IdP the metadata for your Service Provider.  You will have generated this earlier when you ran <code>metagen.sh</code>.  Copy off your EPrints server the file that this wrote (e.g. to <tt>/etc/shibboleth/foo/sp-metadata.xml</tt>) and send it to the Shibboleth IdP administrator.  They should be able to upload this to register EPrints as a Service Provider application.

* Once registered, use a web browser to go to '''/shibboleth/login''' page for your repository, (e.g. ''https://foo.eprints.org/shibboleth/login'') again.  This time you should be prompted for a username and password on the Shibboleth IdP site. Once you have typed this in and clicked to login, you should be returned to EPrints on the '''/cgi/users/home''' page for your repository.  If not, see [[#Login_Issues|Login Issues]] under [[#Troubleshooting|Troubleshooting]] below.