Difference between revisions of "Shibboleth"

From EPrints Documentation
Jump to: navigation, search
(Link to more recent page)
(Updated Shibboleth page with instructions for CentOS 7, that can be augmented for other OS)
Line 1: Line 1:
−
2014-06-30: Please see: [[Shibboleth authentication]].
+
'''This page details how to install and integrate Shibboleth with EPrints 3.3 on a CentOS 7 operating system.'''  The process should be fairly similar for other modern RedHat-based Linux distributions such as RHEL 7 and Fedora 21/22.  However, it will somewhat different for Debian-based Linux, such as Ubuntu and Debian itself and other Linux distribution.  Typically. this just be different package names and different commands to manage applications.
  
−
The link below is dead, but the content can be found: https://web.archive.org/web/20070613214924/https://gabriel.lse.ac.uk/twiki/pub/Projects/ShibbolethIntegration/install.html - although this is EPrints 2.3.
+
'''Generally, it is a good idea to run EPrints with HTTPS when using Shibboleth authentication for increased security on the attributes being sent back by the Shibboleth Identity Provider (IdP).  Therefore, it is assumed that EPrints has already been set up to use HTTPS and there already exists an ssl/securevhost.conf under the archive directory structure.'''
 +
 
 +
== Installing Shibboleth ==
 +
* First, add the Shibboleth repository to your list of Yum repositories:
 +
  root> cd /etc/yum.repos.d/
 +
  root> wget http://download.opensuse.org/repositories/security:shibboleth/CentOS_7/security:shibboleth.repo
 +
 
 +
* Now you can uses Yum to install all package dependencies:
 +
  root> yum install log4shib opensaml shibboleth unixODBC xerces-c xml-security-c xmltooling
 +
 
 +
* You may be prompted to accept the importing of the key for the Shibboleth repository, for which you should enter '''y''' and press enter.
 +
 
 +
* Once all the packages are installed you will need to specify the use of Shibboleth Curl library should be loaded by adding the following line to '''/etc/ld.so.conf.d/shibboleth_libs.conf''':
 +
  /opt/shibboleth/lib64
 +
 
 +
* Once you have done that run '''ldconfig''' and then check '''shibd''' has no issues:
 +
  root> ldconfig
 +
  root> shibd -t
 +
 
 +
* ''shibd -t'' should return a couple of warning, like those listed below.  These are due to it not being configured yet.
 +
  2015-05-11 10:39:01 WARN Shibboleth.Application : insecure cookieProps setting, set to "https" for SSL/TLS-only usage
 +
  2015-05-11 10:39:01 WARN Shibboleth.Application : handlerSSL should be enabled for SSL/TLS-enabled web sites
 +
  2015-05-11 10:39:01 WARN Shibboleth.Application : no MetadataProvider available, configure at least one for standard SSO usage
 +
  overall configuration is loadable, check console for non-fatal problems
 +
 
 +
* If there are no other warning or error messages from ''shibd -t'', you can start it properly and check to make sure it is running.
 +
  root> systemctl start shibd.service
 +
  root> ps aux | grep shib
 +
  shibd    29338  0.4  0.7 419784 15024 ?        Ssl  11:16  0:00 /usr/sbin/shibd -p /var/run/shibboleth/shibd.pid -f -w 30
 +
  root    29345  0.0  0.0 112640  940 pts/2    S+  11:17  0:00 grep --color=auto -i shib
 +
 
 +
 
 +
== Configuring Shibboleth ==
 +
* Replace '''/etc/shibboleth/shibboleth2.xml''' with the following.  Substituting '''foo.eprints.org''' for the hostname of your EPrints repository, '''https://shib.foo.example.org/idp/shibboleth''' with the entity ID for you Shibboleth Identity Provider and '''foo''' in the pathname of files with the name or your repository (e.g. ''foo/attribute-map.xml'' becomes ''myrepo/attribute-map.xml'').
 +
 
 +
  <SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
 +
    xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
 +
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
 +
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"   
 +
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
 +
    clockSkew="180">
 +
 
 +
    <ApplicationDefaults entityID="https://foo.eprints.org/shibboleth"
 +
                        REMOTE_USER="eppn persistent-id targeted-id">
 +
 
 +
      <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
 +
                  checkAddress="false" handlerSSL="true" cookieProps="https">
 +
        <SSO entityID="https://shib.foo.example.org/idp/shibboleth">
 +
              SAML2 SAML1
 +
        </SSO>
 +
        <Logout>SAML2 Local</Logout>
 +
        <Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>
 +
        <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>
 +
        <Handler type="Session" Location="/Session" showAttributeValues="false"/>
 +
        <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
 +
      </Sessions>
 +
 
 +
      <Errors supportContact="root@localhost" helpLocation="/about.html" styleSheet="/shibboleth/main.css"/>
 +
      <MetadataProvider type="XML" file="foo/idp-metadata.xml"/>
 +
      <AttributeExtractor type="XML" validate="true" reloadChanges="false" path="foo/attribute-map.xml"/>
 +
      <AttributeResolver type="Query" subjectMatch="true"/>
 +
      <AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
 +
      <CredentialResolver type="File" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>
 +
 
 +
    </ApplicationDefaults>
 +
 
 +
    <SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
 +
    <ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>
 +
   
 +
  </SPConfig>
 +
 
 +
* Create the directory '''/etc/shibboleth/foo''', substituting ''foo'' for your repository name.
 +
  root> mkdir /etc/shibboleth/foo
 +
 
 +
* Copy '''attribute-map.xml''' into this new directory.
 +
  cp /etc/shibboleth/attribute-map.xml /etc/shibboleth/foo/
 +
 
 +
* Temporarily rename '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/''' to '''sp-cert.pem.old''' and '''sp-key.pem.old'''.
 +
  root> cd /etc/shibboleth
 +
  root> mv sp-cert.pem sp-cert.pem.old
 +
  root> mv sp-key.pem sp-key.pem.old
 +
 
 +
* Run '''keygen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository name.
 +
  root> cd /etc/shibboleth
 +
  root> ./keygen.sh -f -h foo.eprints.org -e https://foo.eprints.org/shibboleth
 +
 
 +
* Move the new '''sp-cert.pem''' and '''sp-key.pem''' to '''/etc/shibboleth/foo/''' amd move the ''.old'' files back in place:
 +
  root> cd /etc/shibboleth
 +
  root> mv sp-cert.pem sp-key.pem foo/
 +
  root> mv sp-cert.pem.old sp-cert.pem
 +
  root> mv sp-key.pem sp-key.pem
 +
 
 +
* Check that '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/foo/''' are still have the owner and group by the '''shibd'''.
 +
  root> ls -l /etc/shibboleth/foo/sp-*
 +
  -rw-r--r-- 1 shibd shibd 1192 May  6 19:04 /etc/shibboleth/foo/sp-cert.pem
 +
  -rw------- 1 shibd shibd 1708 May  6 19:04 /etc/shibboleth/foo/sp-key.pem
 +
 
 +
* Use ''wget'' to download the metadata from your Shibboleth IdP (e.g. shib.foo.example.org) to the '''/etc/shibboleth/foo/''' directory.
 +
  root> wget -O /etc/shibboleth/foo/idp-metadata.xml https://shib.foo.example.org/idp/shibboleth
 +
 
 +
== 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).
 +
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 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, 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, 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/'') ad '''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 logging in users with existing accounts and creating new accounts for users logging in for the first time.  Look under the [[#Customisation|Customisation]] section for advice on how to modify this script to meet your purposes.
 +
use EPrints;
 +
use strict;
 +
 +
my $session = EPrints::Session->new();
 +
my $url = $session->param( "target" );
 +
$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();
 +
 +
  $session->redirect( $url );
 +
}
 +
else {
 +
  $session->redirect( $session->get_repository->get_conf( "base_dir" ) . "/account_required.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 );
 +
  $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 the particular group of people logged in access is restricted to.
 +
 
 +
<?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 Identity Provider 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 Identity Provider the metadata for your Service Provider.  By default this is not external accessible so you will need to do a wget from the command line:
 +
  wget --no-check-certificate -O - -o /dev/null https://localhost/Shibboleth.sso/Metadata | xmllint --format - > ~/sp-metadata.xml
 +
 
 +
* If you get no error messages, this command will have saved you Shibboleth Service Provider metadata in a file in your home directory called '''sp-metadata.xml''', which you can now email to the administrator of the Shibboleth Identity Provider and then wait for them to get back to you to tell you it is registered.
 +
 
 +
* 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 Identity Provider site. Once you have typed this in and clicked to login.  You should be returned to EPrints and be on the '''/cgi/users/home''' page for your repository.  If not see [[#Login_Issues|Login_Issues]] under [[#Troubleshooting|Troubleshooting]] below.
 +
 
 +
== Troubleshooting ==
 +
 
 +
=== 1. Apache Configuration Issues ===
 +
To be added.
 +
 
 +
=== 2. Shibboleth Configuration Issues ===
 +
To be added.
 +
 
 +
=== 3. Login Issues ===
 +
To be added.
 +
 
 +
 
 +
== Customisation ==
 +
 
 +
=== Shibboleth /etc/shibboleth/foo/attribute-map.xml config ===
 +
To be added.
 +
 
 +
=== EPrints /shibboleth/login script ===
 +
To be added.
 +
 
 +
 
 +
== Further Information ==
 +
* Older instructions of how to set up EPrints for Shibboleth using UK Access management Federation discovery service is available [[Shibboleth authentication|here]].
 +
 
 +
* For general information about installing and configuring Shibboleth [http://shibboleth.internet2.edu/ click here].
  
−
----
 
  
−
For the moment there's only this external paper with regard to [http://shibboleth.internet2.edu/ Shibboleth]:
 
  
−
"This add on for the EPrints system enables a user to login using a Shibbleth authentication server. It does this whilst still maintaing the ability to login using the existing EPrints authentication scheme. This is acheived by altering the existing EPrints authentication to one that uses a simple cookie based authentication tracking scheme. A table is added to the database for each archive to track the cookies of currently logged in users."
 
−
* https://gabriel.lse.ac.uk/twiki/pub/Projects/ShibbolethIntegration/install.html
 
  
 
[[Category:Authentication]]
 
[[Category:Authentication]]

Revision as of 14:47, 11 May 2015

This page details how to install and integrate Shibboleth with EPrints 3.3 on a CentOS 7 operating system. The process should be fairly similar for other modern RedHat-based Linux distributions such as RHEL 7 and Fedora 21/22. However, it will somewhat different for Debian-based Linux, such as Ubuntu and Debian itself and other Linux distribution. Typically. this just be different package names and different commands to manage applications.

Generally, it is a good idea to run EPrints with HTTPS when using Shibboleth authentication for increased security on the attributes being sent back by the Shibboleth Identity Provider (IdP). Therefore, it is assumed that EPrints has already been set up to use HTTPS and there already exists an ssl/securevhost.conf under the archive directory structure.

Installing Shibboleth

  • First, add the Shibboleth repository to your list of Yum repositories:
 root> cd /etc/yum.repos.d/
 root> wget http://download.opensuse.org/repositories/security:shibboleth/CentOS_7/security:shibboleth.repo
  • Now you can uses Yum to install all package dependencies:
 root> yum install log4shib opensaml shibboleth unixODBC xerces-c xml-security-c xmltooling
  • You may be prompted to accept the importing of the key for the Shibboleth repository, for which you should enter y and press enter.
  • Once all the packages are installed you will need to specify the use of Shibboleth Curl library should be loaded by adding the following line to /etc/ld.so.conf.d/shibboleth_libs.conf:
 /opt/shibboleth/lib64
  • Once you have done that run ldconfig and then check shibd has no issues:
 root> ldconfig
 root> shibd -t
  • shibd -t should return a couple of warning, like those listed below. These are due to it not being configured yet.
 2015-05-11 10:39:01 WARN Shibboleth.Application : insecure cookieProps setting, set to "https" for SSL/TLS-only usage
 2015-05-11 10:39:01 WARN Shibboleth.Application : handlerSSL should be enabled for SSL/TLS-enabled web sites
 2015-05-11 10:39:01 WARN Shibboleth.Application : no MetadataProvider available, configure at least one for standard SSO usage
 overall configuration is loadable, check console for non-fatal problems
  • If there are no other warning or error messages from shibd -t, you can start it properly and check to make sure it is running.
 root> systemctl start shibd.service
 root> ps aux | grep shib
 shibd    29338  0.4  0.7 419784 15024 ?        Ssl  11:16   0:00 /usr/sbin/shibd -p /var/run/shibboleth/shibd.pid -f -w 30
 root     29345  0.0  0.0 112640   940 pts/2    S+   11:17   0:00 grep --color=auto -i shib


Configuring Shibboleth

  • Replace /etc/shibboleth/shibboleth2.xml with the following. Substituting foo.eprints.org for the hostname of your EPrints repository, https://shib.foo.example.org/idp/shibboleth with the entity ID for you Shibboleth Identity Provider and foo in the pathname of files with the name or your repository (e.g. foo/attribute-map.xml becomes myrepo/attribute-map.xml).
 <SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
   xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
   xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
   xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"    
   xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
   clockSkew="180">
 
   <ApplicationDefaults entityID="https://foo.eprints.org/shibboleth"
                        REMOTE_USER="eppn persistent-id targeted-id">
 
     <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
                 checkAddress="false" handlerSSL="true" cookieProps="https">
       <SSO entityID="https://shib.foo.example.org/idp/shibboleth">
             SAML2 SAML1
       </SSO>
       <Logout>SAML2 Local</Logout>
       <Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>
       <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>
       <Handler type="Session" Location="/Session" showAttributeValues="false"/>
       <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
     </Sessions>
 
     <Errors supportContact="root@localhost" helpLocation="/about.html" styleSheet="/shibboleth/main.css"/>
     <MetadataProvider type="XML" file="foo/idp-metadata.xml"/>
     <AttributeExtractor type="XML" validate="true" reloadChanges="false" path="foo/attribute-map.xml"/>
     <AttributeResolver type="Query" subjectMatch="true"/>
     <AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
     <CredentialResolver type="File" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>
 
   </ApplicationDefaults>
 
   <SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
   <ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>
   
 </SPConfig>
  • Create the directory /etc/shibboleth/foo, substituting foo for your repository name.
 root> mkdir /etc/shibboleth/foo
  • Copy attribute-map.xml into this new directory.
 cp /etc/shibboleth/attribute-map.xml /etc/shibboleth/foo/
  • Temporarily rename sp-cert.pem and sp-key.pem in /etc/shibboleth/ to sp-cert.pem.old and sp-key.pem.old.
 root> cd /etc/shibboleth
 root> mv sp-cert.pem sp-cert.pem.old
 root> mv sp-key.pem sp-key.pem.old
  • Run keygen.sh from the /etc/shibboleth/ directory, as follows replacing foo.eprints.org with your EPrints repository name.
 root> cd /etc/shibboleth
 root> ./keygen.sh -f -h foo.eprints.org -e https://foo.eprints.org/shibboleth
  • Move the new sp-cert.pem and sp-key.pem to /etc/shibboleth/foo/ amd move the .old files back in place:
 root> cd /etc/shibboleth
 root> mv sp-cert.pem sp-key.pem foo/
 root> mv sp-cert.pem.old sp-cert.pem
 root> mv sp-key.pem sp-key.pem
  • Check that sp-cert.pem and sp-key.pem in /etc/shibboleth/foo/ are still have the owner and group by the shibd.
 root> ls -l /etc/shibboleth/foo/sp-*
 -rw-r--r-- 1 shibd shibd 1192 May  6 19:04 /etc/shibboleth/foo/sp-cert.pem
 -rw------- 1 shibd shibd 1708 May  6 19:04 /etc/shibboleth/foo/sp-key.pem
  • Use wget to download the metadata from your Shibboleth IdP (e.g. shib.foo.example.org) to the /etc/shibboleth/foo/ directory.
 root> wget -O /etc/shibboleth/foo/idp-metadata.xml https://shib.foo.example.org/idp/shibboleth

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).
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 "<html><head/><body><code>\n";

foreach my $key (sort keys(%ENV)) {
  print "<p>$key = $ENV{$key}</p>";
}
 
print "</code></body></html>";
$session->terminate;
exit;
  • Now restart Shibboleth and Apache:
 root> systemctl restart shibd.service
 root> apachectl restart

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/) ad 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 logging in users with existing accounts and creating new accounts for users logging in for the first time. Look under the Customisation section for advice on how to modify this script to meet your purposes.
use EPrints;
use strict;

my $session = EPrints::Session->new();
my $url = $session->param( "target" );
$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();

  $session->redirect( $url );
}
else {
  $session->redirect( $session->get_repository->get_conf( "base_dir" ) . "/account_required.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 );
  $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 the particular group of people logged in access is restricted to.
<?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>
   <p style='text-align: center;'>Please note that only staff and students of the University of Foo may log in to <epc:phrase ref="archive_name" /></p>
</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 Identity Provider 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 Identity Provider the metadata for your Service Provider. By default this is not external accessible so you will need to do a wget from the command line:
 wget --no-check-certificate -O - -o /dev/null https://localhost/Shibboleth.sso/Metadata | xmllint --format - > ~/sp-metadata.xml
  • If you get no error messages, this command will have saved you Shibboleth Service Provider metadata in a file in your home directory called sp-metadata.xml, which you can now email to the administrator of the Shibboleth Identity Provider and then wait for them to get back to you to tell you it is registered.
  • 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 Identity Provider site. Once you have typed this in and clicked to login. You should be returned to EPrints and be on the /cgi/users/home page for your repository. If not see Login_Issues under Troubleshooting below.

Troubleshooting

1. Apache Configuration Issues

To be added.

2. Shibboleth Configuration Issues

To be added.

3. Login Issues

To be added.


Customisation

Shibboleth /etc/shibboleth/foo/attribute-map.xml config

To be added.

EPrints /shibboleth/login script

To be added.


Further Information

  • Older instructions of how to set up EPrints for Shibboleth using UK Access management Federation discovery service is available here.
  • For general information about installing and configuring Shibboleth click here.
Retrieved from ‘https://wiki.eprints.org/w/index.php?title=Shibboleth&oldid=11163’