EPrints Documentation - User contributions [en-gb]

Shibboleth

2025-01-21T15:17:36Z

Ejo1f20: /* Configuring Shibboleth */

{{Manual}}
'''This page details how to install and integrate Shibboleth with EPrints 3.3.x or 3.4.x on a CentOS 7 operating system.''' The process should be fairly similar for other comparable Red Hat based Linux distributions such as RHEL 7 and Fedora 21/22. These instructions should also be generally applicable to later versions of RHEL-based Linux (e.g. Rocky Linux 8, Red Hat Enterprise Linux 9, etc.). However, they may be somewhat different for Debian-based Linux, such as Ubuntu and Debian itself and other Linux distributions. Typically, this will 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 (if you need this for a different RHEL-based Linux distribution fill in the form at https://shibboleth.net/downloads/service-provider/latest/RPMS/):
root> wget -O /etc/yum.repos.d/shibboleth.repo https://shibboleth.net/cgi-bin/sp_repo.cgi?platform=CentOS_7

* Now you can use 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 type '''y''' and press enter.

* Once you have done that, test that '''shibd''' has no issues:
root> LD_LIBRARY_PATH=/opt/shibboleth/lib64 shibd -t

* ''shibd -t'' should return a couple of warning, like those listed below. These are due to it not yet being configured.
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. You may also want ensure Shibboleth starts at boot using '''systemctl enable'''
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
root> systemctl enable shibd.service

== Configuring Shibboleth ==
* Replace '''/etc/shibboleth/shibboleth2.xml''' with the following. Substitute '''foo.eprints.org''' for the hostname of your EPrints repository, '''https://shib.foo.example.org/idp/shibboleth''' with the entity ID for you Shibboleth IdP and '''foo''' in the pathname of files with the name or your repository (e.g. ''foo/attribute-map.xml'' becomes ''myrepo/attribute-map.xml''). '''(This configuration is intended for Shibboleth SP version 2.x and is liable to cause deprecation warnings if you have installed a recent version of Shibboleth from a package repository. [[Shibboleth/3.x|Here is a default shibboleth2.xml configuration for Shibboleth 3.x]]).'''

<SPConfig xmlns="urn:mace:shibboleth:3.0:native:sp:config"
xmlns:conf="urn:mace:shibboleth:3.0:native:sp:config"
clockSkew="180">

<ApplicationDefaults entityID="https://foo.eprints.org/shibboleth"
REMOTE_USER="eppn subject-id pairwise-id persistent-id"
cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">

<Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
checkAddress="false" handlerSSL="true" cookieProps="https"
redirectLimit="exact">
<SSO entityID="https://shib.foo.example.org/idp/shibboleth">SAML2</SSO>
<Logout>SAML2 Local</Logout>
<LogoutInitiator type="Admin" Location="/Logout/Admin" acl="127.0.0.1 ::1" />
<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" path="foo/idp-metadata.xml"/>
<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="foo/attribute-map.xml"/>
<AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
<CredentialResolver type="File" use="signing" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>
<CredentialResolver type="File" use="encryption" 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 hostname.
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/''' and 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.old sp-key.pem

* Check that '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/foo/''' still have the owner and group '''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

* Run '''metagen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository hostname. You will ultimately need to send the output of this to the person managing the Shibboleth IdP server with which you want to register your EPrints repository as a service.
root> cd /etc/shibboleth
root> ./metagen.sh -ALO -c foo/sp-cert.pem -h foo.eprints.org -e https://foo.eprints.org/shibboleth > foo/sp_metadata.xml

* Modify ''' foo/sp_metadata.xml''' to add in the namepace definitions by separately changing the <code>md:EntityDescriptor</code> and <code>ds:KeyInfo</code> lines as follows from:
<md:EntityDescriptor entityID="https://foo.eprints.org/shibboleth">
...
...
<ds:KeyInfo>
to:
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://foo.eprints.org/shibboleth">
...
...
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

* 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

=== Using Remote IdP Metatdata ===

As IdP Metadata may expire, you may want to use the remote metadata URL rather than a local copy. This is what you need to do to switch to using remote IdP metadata:

* Edit the '''MetadataProvider''' line to something like the following. The reloadInterval is best set to 7200 but this can be set less frequently:

<MetadataProvider type="XML" url="https://shib.foo.example.org/idp/metadata.xml" backingFilePath="foo/idp-metadata.xml" reloadInterval="7200"/>

* Make sure the reloadInterval is appropriate for the IdP metadata you are downloading. If you have large metadata file,(e.g. from a federated metadata service containing metadata for other IdPs), then it may be better to set this higher than the default. However, the configuration checker may warn you that your reload interval is too long, so you may have to choose to ignore this, if you want to avoid downloading a large federated metadata file too often.

* Make sure that the directory '''/etc/shibboleth/foo/''' and '''/etc/shibboleth/foo/idp-metadata.xml''' if it already exists) are owned by '''shibd''':

chown shibd:shibd /etc/shibboleth/foo/
chown shibd:shibd /etc/shibboleth/foo/idp-metadata.xml

* To test Shibboleth you will need to make sure your '''LD_LIBRARY_PATH''' is set the same as shibd would have when started using ''systemctl shibd start''. This should return the message: ''overall configuration is loadable, check console for non-fatal problems''.

LD_LIBRARY_PATH=/opt/shibboleth/lib64:$LD_LIBRARY_PATH shibd -t

* The above message is because it is now advised not to leave the MetadataGenerator enabled unnecessarily. However, whilst you are setting up Shibboleth, it is useful to have the metadata generator, save you needing to build your own Service Provider metadata file to register with your Identity Provider. Later on you can comment out the MetadataGenerator line to stop getting this warning message.

* Now you can restart '''shibd''' properly:

systemctl restart shibd

== 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 "<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

* 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>
<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 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.

== Troubleshooting ==

=== Apache Configuration Issues ===
==== Apache 2.2 (and lower) Configuration for EPrints Shibboleth Integration ====
* Similarly to the instructions for Apache 2.4 and above, place the slightly different following configuration after the '''Include''' line for ''apache_ssl/foo.conf'', (substituting '''foo''' for your archive's name):

Alias /shibboleth /opt/eprints3/archives/foo/shibboleth
<Directory "/opt/eprints3/archives/foo/shibboleth">
SetHandler perl-script
PerlHandler ModPerl::Registry
PerlSendHeader Off
Options ExecCGI FollowSymLinks

AuthType shibboleth
ShibRequireSession On
require valid-user
</Directory>

<Location /cgi/shibboleth>
AuthType shibboleth
ShibRequireSession On
require valid-user
</Location>

=== Shibboleth Configuration Issues ===
==== With attribute-map.xml ====
When authenticating using Shibboleth to login to EPrints you may see the following line in '''/var/log/shibboleth.shibd.log'''

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: urn:mace:dir:attribute-def:department

In some cases this might not be an issue, as EPrints does not necessarily to make use of all the attributes returned by the IdP but without a mapping in attribute-map.xml. In this case '''urn:mace:dir:attribute-def:department''' is not by default needed by EPrints to create/update a user account. However, values like '''sn''', '''givenName''' and '''mail''' are but if you have used the attribute-map.xml provided later on the page you should not see a line like above in '''shibd.log'''. In some cases you may still see an line like this in the log even if you think you have defined the attribute. The line below demonstrate two known issues:

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: givenName, Format:urn:oasis:names:tc:SAML:2.0:attrname-format:basic

# The attribute itself has no namespace it is just ''''givenName''' rather than '''urn:mace:dir:attribute-def:givenName'''
# The attribute has a format that most also be defined in the attribute-map.xml attribute.

Below shows how to both include the format, which is required for the attribute to be successful mapped. As well as define the name of the attribute without a namespace:

<Attribute name="givenName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>

A typical Shibboleth IdP would have both a namespaced attribute name and would not apply a format to an attribute that is a simple text string. Therefore it is worth enquiring with the IdP provider if either of these two happen to be the case.

==== With idp-metadata.xml ====
If you want to be able extract scoped attributes (e.g. '''eduPersonPrincipalName''' otherwise described as '''eppn'''). Then you will need to ensure that the expected scope of this attribute, (effectively the domain part in eduPersonPrincipalName is the scope or one of the scopes in the idp-metadata.xml you downloaded from the Shibboleth IdP. For example if the '''eduPersonPrincipalName''' is '''bar@foo.ac.uk'''. Then the following should be defined in idp-metadata.xml ('''N.B. the namespace abbreviations (md: and shibmd:) may be different for the IdP you are working with'''):

<md:Extensions>
<shibmd:Scope regexp="false">foo.ac.uk</shibmd:Scope>
</md:Extensions>

=== Login Issues ===
To be added.

== Customisation ==

=== Shibboleth /etc/shibboleth/foo/attribute-map.xml config ===
This is adapted from the default '''attribute-map.xml''' provided when the Shibboleth SP package is installed to only include the attribute subsequently used by EPrints Shibboleth Perl script that can be found below. Namely:

{| border="1" cellpadding="10" cellspacing="0"
!Field name
!Field description
!SAML v1.1 attribute URN
!SAMLv2 attribute URN
|-
|eppn
|Edu Person Principal Name
|urn:mace:dir:attribute-def:eduPersonPrincipalName
|urn:oid:1.3.6.1.4.1.5923.1.1.1.6
|-
|sn
|Surname
|urn:mace:dir:attribute-def:sn
|urn:oid:2.5.4.4
|-
|givenName
|Given (first) name(s)
|urn:mace:dir:attribute-def:givenName
|urn:oid:2.5.4.42
|-
|mail
|Email address
|urn:mace:dir:attribute-def:mail
|urn:oid:0.9.2342.19200300.100.1.3
|-
|}

You may wish to refer to the default '''attribute-map.xml''' is you want to use other attributes.

<Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>
<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>

<Attribute name="urn:mace:dir:attribute-def:sn" id="sn"/>
<Attribute name="urn:mace:dir:attribute-def:givenName" id="givenName"/>
<Attribute name="urn:mace:dir:attribute-def:mail" id="mail"/>

<Attribute name="urn:oid:2.5.4.4" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="sn"/>
<Attribute name="urn:oid:2.5.4.42" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>
<Attribute name="urn:oid:0.9.2342.19200300.100.1.3" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="mail"/>

</Attributes>

=== EPrints /shibboleth/login script with user account creation ===
This is the standard EPrints Shibboleth login script. It makes a number of assumptions:
# That accounts should be created if they do not already exist for a particular user.
# That you wish to create a standard user account (not an editor administrator) account.
# That the Shibboleth IdP provides all the attributes (eduPersonPrinicpalName (seen as eppn), sn, givenName and mail) required.

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, $given, $family, $email) = (undef, "", "", "");

if( $ENV{eppn} )
{
( $username ) = split( /@/, $ENV{eppn}, 2);
$username = lc( $username );
}
$email = $ENV{mail} if $ENV{mail};
if( $ENV{givenName} )
{
$given = lc( $ENV{givenName} );
$given =~ s/^(.)/uc($1)/e;
$given =~ s/([- ].)/uc($1)/e;
}
if( $ENV{sn} )
{
$family = lc( $ENV{sn} );
$family =~ s/^(.)/uc($1)/e;
$family =~ s/([- ].)/uc($1)/e;
}

return unless EPrints::Utils::is_set( $username );

my $user = $session->user_by_username( $username ); # relying on this to be case insensitive

if( !defined $user )
{
my $usertype = 'user';
$user = EPrints::DataObj::User::create( $session, $usertype );
$user->set_value( "username", $username );
}
my $name = {
given => $given,
family => $family,
};
$user->set_value( "name", $name );
$user->set_value( "email", $email );
$user->commit;
return $user;
}

== 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].

* [https://docs.openathens.net/display/public/TPA/Sign+in+to+a+generic+application+using+OpenAthens#SignintoagenericapplicationusingOpenAthens-SetupthecustomSAMLresourceinOpenAthens Instructions of connection a Shibboleth Service Provider with OpenAthens]

[[Category:Authentication]]

Shibboleth

2025-01-21T14:47:45Z

Ejo1f20: /* Configuring Shibboleth */

{{Manual}}
'''This page details how to install and integrate Shibboleth with EPrints 3.3.x or 3.4.x on a CentOS 7 operating system.''' The process should be fairly similar for other comparable Red Hat based Linux distributions such as RHEL 7 and Fedora 21/22. These instructions should also be generally applicable to later versions of RHEL-based Linux (e.g. Rocky Linux 8, Red Hat Enterprise Linux 9, etc.). However, they may be somewhat different for Debian-based Linux, such as Ubuntu and Debian itself and other Linux distributions. Typically, this will 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 (if you need this for a different RHEL-based Linux distribution fill in the form at https://shibboleth.net/downloads/service-provider/latest/RPMS/):
root> wget -O /etc/yum.repos.d/shibboleth.repo https://shibboleth.net/cgi-bin/sp_repo.cgi?platform=CentOS_7

* Now you can use 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 type '''y''' and press enter.

* Once you have done that, test that '''shibd''' has no issues:
root> LD_LIBRARY_PATH=/opt/shibboleth/lib64 shibd -t

* ''shibd -t'' should return a couple of warning, like those listed below. These are due to it not yet being configured.
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. You may also want ensure Shibboleth starts at boot using '''systemctl enable'''
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
root> systemctl enable shibd.service

== Configuring Shibboleth ==
* Replace '''/etc/shibboleth/shibboleth2.xml''' with the following. Substitute '''foo.eprints.org''' for the hostname of your EPrints repository, '''https://shib.foo.example.org/idp/shibboleth''' with the entity ID for you Shibboleth IdP and '''foo''' in the pathname of files with the name or your repository (e.g. ''foo/attribute-map.xml'' becomes ''myrepo/attribute-map.xml''). '''(This configuration is intended for Shibboleth SP version 2.x and is liable to cause deprecation warnings if you have installed a recent version of Shibboleth from a package repository. [[Shibboleth/3.x|Here is a default shibboleth2.xml configuration for Shibboleth 3.x]]).'''

<SPConfig xmlns="urn:mace:shibboleth:3.0:native:sp:config"
xmlns:conf="urn:mace:shibboleth:3.0:native:sp:config"
clockSkew="180">

<ApplicationDefaults entityID="https://foo.eprints.org/shibboleth"
REMOTE_USER="eppn subject-id pairwise-id persistent-id"
cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">

<Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
checkAddress="false" handlerSSL="true" cookieProps="https"
redirectLimit="exact">
<SSO entityID="https://shib.foo.example.org/idp/shibboleth">SAML2</SSO>
<Logout>SAML2 Local</Logout>
<LogoutInitiator type="Admin" Location="/Logout/Admin" acl="127.0.0.1 ::1" />
<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" path="foo/idp-metadata.xml"/>
<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="foo/attribute-map.xml"/>
<AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
<CredentialResolver type="File" use="signing" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>
<CredentialResolver type="File" use="encryption" 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 hostname.
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/''' and 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.old sp-key.pem

* Check that '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/foo/''' still have the owner and group '''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

* Run '''metagen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository hostname. You will ultimately need to send the output of this to the person managing the Shibboleth IdP server with which you want to register your EPrints repository as a service.
root> cd /etc/shibboleth
root> ./metagen.sh -ALO -c foo/sp-cert.pem -h foo.eprints.org -e https://foo.eprints.org/shibboleth > foo/sp_metadata.xml

* Modify ''' foo/sp_metadata.xml''' to add in the namepace definitions by separately changing the <code>md:EntityDescriptor</code> and <code>ds:KeyInfo</code> lines as follows from:
<md:EntityDescriptor entityID="https://for.eprints.org/shibboleth">
...
...
<ds:KeyInfo>
to:
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://for.eprints.org/shibboleth">
...
...
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

* 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

=== Using Remote IdP Metatdata ===

As IdP Metadata may expire, you may want to use the remote metadata URL rather than a local copy. This is what you need to do to switch to using remote IdP metadata:

* Edit the '''MetadataProvider''' line to something like the following. The reloadInterval is best set to 7200 but this can be set less frequently:

<MetadataProvider type="XML" url="https://shib.foo.example.org/idp/metadata.xml" backingFilePath="foo/idp-metadata.xml" reloadInterval="7200"/>

* Make sure the reloadInterval is appropriate for the IdP metadata you are downloading. If you have large metadata file,(e.g. from a federated metadata service containing metadata for other IdPs), then it may be better to set this higher than the default. However, the configuration checker may warn you that your reload interval is too long, so you may have to choose to ignore this, if you want to avoid downloading a large federated metadata file too often.

* Make sure that the directory '''/etc/shibboleth/foo/''' and '''/etc/shibboleth/foo/idp-metadata.xml''' if it already exists) are owned by '''shibd''':

chown shibd:shibd /etc/shibboleth/foo/
chown shibd:shibd /etc/shibboleth/foo/idp-metadata.xml

* To test Shibboleth you will need to make sure your '''LD_LIBRARY_PATH''' is set the same as shibd would have when started using ''systemctl shibd start''. This should return the message: ''overall configuration is loadable, check console for non-fatal problems''.

LD_LIBRARY_PATH=/opt/shibboleth/lib64:$LD_LIBRARY_PATH shibd -t

* The above message is because it is now advised not to leave the MetadataGenerator enabled unnecessarily. However, whilst you are setting up Shibboleth, it is useful to have the metadata generator, save you needing to build your own Service Provider metadata file to register with your Identity Provider. Later on you can comment out the MetadataGenerator line to stop getting this warning message.

* Now you can restart '''shibd''' properly:

systemctl restart shibd

== 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 "<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

* 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>
<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 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.

== Troubleshooting ==

=== Apache Configuration Issues ===
==== Apache 2.2 (and lower) Configuration for EPrints Shibboleth Integration ====
* Similarly to the instructions for Apache 2.4 and above, place the slightly different following configuration after the '''Include''' line for ''apache_ssl/foo.conf'', (substituting '''foo''' for your archive's name):

Alias /shibboleth /opt/eprints3/archives/foo/shibboleth
<Directory "/opt/eprints3/archives/foo/shibboleth">
SetHandler perl-script
PerlHandler ModPerl::Registry
PerlSendHeader Off
Options ExecCGI FollowSymLinks

AuthType shibboleth
ShibRequireSession On
require valid-user
</Directory>

<Location /cgi/shibboleth>
AuthType shibboleth
ShibRequireSession On
require valid-user
</Location>

=== Shibboleth Configuration Issues ===
==== With attribute-map.xml ====
When authenticating using Shibboleth to login to EPrints you may see the following line in '''/var/log/shibboleth.shibd.log'''

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: urn:mace:dir:attribute-def:department

In some cases this might not be an issue, as EPrints does not necessarily to make use of all the attributes returned by the IdP but without a mapping in attribute-map.xml. In this case '''urn:mace:dir:attribute-def:department''' is not by default needed by EPrints to create/update a user account. However, values like '''sn''', '''givenName''' and '''mail''' are but if you have used the attribute-map.xml provided later on the page you should not see a line like above in '''shibd.log'''. In some cases you may still see an line like this in the log even if you think you have defined the attribute. The line below demonstrate two known issues:

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: givenName, Format:urn:oasis:names:tc:SAML:2.0:attrname-format:basic

# The attribute itself has no namespace it is just ''''givenName''' rather than '''urn:mace:dir:attribute-def:givenName'''
# The attribute has a format that most also be defined in the attribute-map.xml attribute.

Below shows how to both include the format, which is required for the attribute to be successful mapped. As well as define the name of the attribute without a namespace:

<Attribute name="givenName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>

A typical Shibboleth IdP would have both a namespaced attribute name and would not apply a format to an attribute that is a simple text string. Therefore it is worth enquiring with the IdP provider if either of these two happen to be the case.

==== With idp-metadata.xml ====
If you want to be able extract scoped attributes (e.g. '''eduPersonPrincipalName''' otherwise described as '''eppn'''). Then you will need to ensure that the expected scope of this attribute, (effectively the domain part in eduPersonPrincipalName is the scope or one of the scopes in the idp-metadata.xml you downloaded from the Shibboleth IdP. For example if the '''eduPersonPrincipalName''' is '''bar@foo.ac.uk'''. Then the following should be defined in idp-metadata.xml ('''N.B. the namespace abbreviations (md: and shibmd:) may be different for the IdP you are working with'''):

<md:Extensions>
<shibmd:Scope regexp="false">foo.ac.uk</shibmd:Scope>
</md:Extensions>

=== Login Issues ===
To be added.

== Customisation ==

=== Shibboleth /etc/shibboleth/foo/attribute-map.xml config ===
This is adapted from the default '''attribute-map.xml''' provided when the Shibboleth SP package is installed to only include the attribute subsequently used by EPrints Shibboleth Perl script that can be found below. Namely:

{| border="1" cellpadding="10" cellspacing="0"
!Field name
!Field description
!SAML v1.1 attribute URN
!SAMLv2 attribute URN
|-
|eppn
|Edu Person Principal Name
|urn:mace:dir:attribute-def:eduPersonPrincipalName
|urn:oid:1.3.6.1.4.1.5923.1.1.1.6
|-
|sn
|Surname
|urn:mace:dir:attribute-def:sn
|urn:oid:2.5.4.4
|-
|givenName
|Given (first) name(s)
|urn:mace:dir:attribute-def:givenName
|urn:oid:2.5.4.42
|-
|mail
|Email address
|urn:mace:dir:attribute-def:mail
|urn:oid:0.9.2342.19200300.100.1.3
|-
|}

You may wish to refer to the default '''attribute-map.xml''' is you want to use other attributes.

<Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>
<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>

<Attribute name="urn:mace:dir:attribute-def:sn" id="sn"/>
<Attribute name="urn:mace:dir:attribute-def:givenName" id="givenName"/>
<Attribute name="urn:mace:dir:attribute-def:mail" id="mail"/>

<Attribute name="urn:oid:2.5.4.4" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="sn"/>
<Attribute name="urn:oid:2.5.4.42" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>
<Attribute name="urn:oid:0.9.2342.19200300.100.1.3" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="mail"/>

</Attributes>

=== EPrints /shibboleth/login script with user account creation ===
This is the standard EPrints Shibboleth login script. It makes a number of assumptions:
# That accounts should be created if they do not already exist for a particular user.
# That you wish to create a standard user account (not an editor administrator) account.
# That the Shibboleth IdP provides all the attributes (eduPersonPrinicpalName (seen as eppn), sn, givenName and mail) required.

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, $given, $family, $email) = (undef, "", "", "");

if( $ENV{eppn} )
{
( $username ) = split( /@/, $ENV{eppn}, 2);
$username = lc( $username );
}
$email = $ENV{mail} if $ENV{mail};
if( $ENV{givenName} )
{
$given = lc( $ENV{givenName} );
$given =~ s/^(.)/uc($1)/e;
$given =~ s/([- ].)/uc($1)/e;
}
if( $ENV{sn} )
{
$family = lc( $ENV{sn} );
$family =~ s/^(.)/uc($1)/e;
$family =~ s/([- ].)/uc($1)/e;
}

return unless EPrints::Utils::is_set( $username );

my $user = $session->user_by_username( $username ); # relying on this to be case insensitive

if( !defined $user )
{
my $usertype = 'user';
$user = EPrints::DataObj::User::create( $session, $usertype );
$user->set_value( "username", $username );
}
my $name = {
given => $given,
family => $family,
};
$user->set_value( "name", $name );
$user->set_value( "email", $email );
$user->commit;
return $user;
}

== 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].

* [https://docs.openathens.net/display/public/TPA/Sign+in+to+a+generic+application+using+OpenAthens#SignintoagenericapplicationusingOpenAthens-SetupthecustomSAMLresourceinOpenAthens Instructions of connection a Shibboleth Service Provider with OpenAthens]

[[Category:Authentication]]

Shibboleth

2025-01-21T14:22:54Z

Ejo1f20:

{{Manual}}
'''This page details how to install and integrate Shibboleth with EPrints 3.3.x or 3.4.x on a CentOS 7 operating system.''' The process should be fairly similar for other comparable Red Hat based Linux distributions such as RHEL 7 and Fedora 21/22. These instructions should also be generally applicable to later versions of RHEL-based Linux (e.g. Rocky Linux 8, Red Hat Enterprise Linux 9, etc.). However, they may be somewhat different for Debian-based Linux, such as Ubuntu and Debian itself and other Linux distributions. Typically, this will 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 (if you need this for a different RHEL-based Linux distribution fill in the form at https://shibboleth.net/downloads/service-provider/latest/RPMS/):
root> wget -O /etc/yum.repos.d/shibboleth.repo https://shibboleth.net/cgi-bin/sp_repo.cgi?platform=CentOS_7

* Now you can use 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 type '''y''' and press enter.

* Once you have done that, test that '''shibd''' has no issues:
root> LD_LIBRARY_PATH=/opt/shibboleth/lib64 shibd -t

* ''shibd -t'' should return a couple of warning, like those listed below. These are due to it not yet being configured.
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. You may also want ensure Shibboleth starts at boot using '''systemctl enable'''
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
root> systemctl enable shibd.service

== Configuring Shibboleth ==
* Replace '''/etc/shibboleth/shibboleth2.xml''' with the following. Substitute '''foo.eprints.org''' for the hostname of your EPrints repository, '''https://shib.foo.example.org/idp/shibboleth''' with the entity ID for you Shibboleth IdP and '''foo''' in the pathname of files with the name or your repository (e.g. ''foo/attribute-map.xml'' becomes ''myrepo/attribute-map.xml''). '''(This configuration is intended for Shibboleth SP version 2.x and is liable to cause deprecation warnings if you have installed a recent version of Shibboleth from a package repository. [[Shibboleth/3.x|Here is a default shibboleth2.xml configuration for Shibboleth 3.x]]).'''

<SPConfig xmlns="urn:mace:shibboleth:3.0:native:sp:config"
xmlns:conf="urn:mace:shibboleth:3.0:native:sp:config"
clockSkew="180">

<ApplicationDefaults entityID="https://foo.eprints.org/shibboleth"
REMOTE_USER="eppn subject-id pairwise-id persistent-id"
cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">

<Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
checkAddress="false" handlerSSL="true" cookieProps="https"
redirectLimit="exact">
<SSO entityID="https://shib.foo.example.org/idp/shibboleth">SAML2</SSO>
<Logout>SAML2 Local</Logout>
<LogoutInitiator type="Admin" Location="/Logout/Admin" acl="127.0.0.1 ::1" />
<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" path="foo/idp-metadata.xml"/>
<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="foo/attribute-map.xml"/>
<AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
<CredentialResolver type="File" use="signing" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>
<CredentialResolver type="File" use="encryption" 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 hostname.
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.old sp-key.pem

* Check that '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/foo/''' still have the owner and group '''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

* Run '''metagen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository hostname. You will ultimately need to send the output of this to the person managing the Shibboleth IdP server with which you want to register your EPrints repository as a service.
root> cd /etc/shibboleth
root> ./metagen.sh -ALO -c foo/sp-cert.pem -h foo.eprints.org -e https://foo.eprints.org/shibboleth > foo/sp_metadata.xml

* Modify ''' foo/sp_metadata.xml''' to add in the namepace definitions by separately changing the <code>md:EntityDescriptor</code> and <code>ds:KeyInfo</code> lines as follows from:
<md:EntityDescriptor entityID="https://for.eprints.org/shibboleth">
...
...
<ds:KeyInfo>
to:
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://for.eprints.org/shibboleth">
...
...
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

* 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

=== Using Remote IdP Metatdata ===

As IdP Metadata may expire, you may want to use the remote metadata URL rather than a local copy. This is what you need to do to switch to using remote IdP metadata:

* Edit the '''MetadataProvider''' line to something like the following. The reloadInterval is best set to 7200 but this can be set less frequently:

<MetadataProvider type="XML" url="https://shib.foo.example.org/idp/metadata.xml" backingFilePath="foo/idp-metadata.xml" reloadInterval="7200"/>

* Make sure the reloadInterval is appropriate for the IdP metadata you are downloading. If you have large metadata file,(e.g. from a federated metadata service containing metadata for other IdPs), then it may be better to set this higher than the default. However, the configuration checker may warn you that your reload interval is too long, so you may have to choose to ignore this, if you want to avoid downloading a large federated metadata file too often.

* Make sure that the directory '''/etc/shibboleth/foo/''' and '''/etc/shibboleth/foo/idp-metadata.xml''' if it already exists) are owned by '''shibd''':

chown shibd:shibd /etc/shibboleth/foo/
chown shibd:shibd /etc/shibboleth/foo/idp-metadata.xml

* To test Shibboleth you will need to make sure your '''LD_LIBRARY_PATH''' is set the same as shibd would have when started using ''systemctl shibd start''. This should return the message: ''overall configuration is loadable, check console for non-fatal problems''.

LD_LIBRARY_PATH=/opt/shibboleth/lib64:$LD_LIBRARY_PATH shibd -t

* The above message is because it is now advised not to leave the MetadataGenerator enabled unnecessarily. However, whilst you are setting up Shibboleth, it is useful to have the metadata generator, save you needing to build your own Service Provider metadata file to register with your Identity Provider. Later on you can comment out the MetadataGenerator line to stop getting this warning message.

* Now you can restart '''shibd''' properly:

systemctl restart shibd

== 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 "<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

* 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>
<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 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.

== Troubleshooting ==

=== Apache Configuration Issues ===
==== Apache 2.2 (and lower) Configuration for EPrints Shibboleth Integration ====
* Similarly to the instructions for Apache 2.4 and above, place the slightly different following configuration after the '''Include''' line for ''apache_ssl/foo.conf'', (substituting '''foo''' for your archive's name):

Alias /shibboleth /opt/eprints3/archives/foo/shibboleth
<Directory "/opt/eprints3/archives/foo/shibboleth">
SetHandler perl-script
PerlHandler ModPerl::Registry
PerlSendHeader Off
Options ExecCGI FollowSymLinks

AuthType shibboleth
ShibRequireSession On
require valid-user
</Directory>

<Location /cgi/shibboleth>
AuthType shibboleth
ShibRequireSession On
require valid-user
</Location>

=== Shibboleth Configuration Issues ===
==== With attribute-map.xml ====
When authenticating using Shibboleth to login to EPrints you may see the following line in '''/var/log/shibboleth.shibd.log'''

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: urn:mace:dir:attribute-def:department

In some cases this might not be an issue, as EPrints does not necessarily to make use of all the attributes returned by the IdP but without a mapping in attribute-map.xml. In this case '''urn:mace:dir:attribute-def:department''' is not by default needed by EPrints to create/update a user account. However, values like '''sn''', '''givenName''' and '''mail''' are but if you have used the attribute-map.xml provided later on the page you should not see a line like above in '''shibd.log'''. In some cases you may still see an line like this in the log even if you think you have defined the attribute. The line below demonstrate two known issues:

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: givenName, Format:urn:oasis:names:tc:SAML:2.0:attrname-format:basic

# The attribute itself has no namespace it is just ''''givenName''' rather than '''urn:mace:dir:attribute-def:givenName'''
# The attribute has a format that most also be defined in the attribute-map.xml attribute.

Below shows how to both include the format, which is required for the attribute to be successful mapped. As well as define the name of the attribute without a namespace:

<Attribute name="givenName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>

A typical Shibboleth IdP would have both a namespaced attribute name and would not apply a format to an attribute that is a simple text string. Therefore it is worth enquiring with the IdP provider if either of these two happen to be the case.

==== With idp-metadata.xml ====
If you want to be able extract scoped attributes (e.g. '''eduPersonPrincipalName''' otherwise described as '''eppn'''). Then you will need to ensure that the expected scope of this attribute, (effectively the domain part in eduPersonPrincipalName is the scope or one of the scopes in the idp-metadata.xml you downloaded from the Shibboleth IdP. For example if the '''eduPersonPrincipalName''' is '''bar@foo.ac.uk'''. Then the following should be defined in idp-metadata.xml ('''N.B. the namespace abbreviations (md: and shibmd:) may be different for the IdP you are working with'''):

<md:Extensions>
<shibmd:Scope regexp="false">foo.ac.uk</shibmd:Scope>
</md:Extensions>

=== Login Issues ===
To be added.

== Customisation ==

=== Shibboleth /etc/shibboleth/foo/attribute-map.xml config ===
This is adapted from the default '''attribute-map.xml''' provided when the Shibboleth SP package is installed to only include the attribute subsequently used by EPrints Shibboleth Perl script that can be found below. Namely:

{| border="1" cellpadding="10" cellspacing="0"
!Field name
!Field description
!SAML v1.1 attribute URN
!SAMLv2 attribute URN
|-
|eppn
|Edu Person Principal Name
|urn:mace:dir:attribute-def:eduPersonPrincipalName
|urn:oid:1.3.6.1.4.1.5923.1.1.1.6
|-
|sn
|Surname
|urn:mace:dir:attribute-def:sn
|urn:oid:2.5.4.4
|-
|givenName
|Given (first) name(s)
|urn:mace:dir:attribute-def:givenName
|urn:oid:2.5.4.42
|-
|mail
|Email address
|urn:mace:dir:attribute-def:mail
|urn:oid:0.9.2342.19200300.100.1.3
|-
|}

You may wish to refer to the default '''attribute-map.xml''' is you want to use other attributes.

<Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>
<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>

<Attribute name="urn:mace:dir:attribute-def:sn" id="sn"/>
<Attribute name="urn:mace:dir:attribute-def:givenName" id="givenName"/>
<Attribute name="urn:mace:dir:attribute-def:mail" id="mail"/>

<Attribute name="urn:oid:2.5.4.4" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="sn"/>
<Attribute name="urn:oid:2.5.4.42" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>
<Attribute name="urn:oid:0.9.2342.19200300.100.1.3" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="mail"/>

</Attributes>

=== EPrints /shibboleth/login script with user account creation ===
This is the standard EPrints Shibboleth login script. It makes a number of assumptions:
# That accounts should be created if they do not already exist for a particular user.
# That you wish to create a standard user account (not an editor administrator) account.
# That the Shibboleth IdP provides all the attributes (eduPersonPrinicpalName (seen as eppn), sn, givenName and mail) required.

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, $given, $family, $email) = (undef, "", "", "");

if( $ENV{eppn} )
{
( $username ) = split( /@/, $ENV{eppn}, 2);
$username = lc( $username );
}
$email = $ENV{mail} if $ENV{mail};
if( $ENV{givenName} )
{
$given = lc( $ENV{givenName} );
$given =~ s/^(.)/uc($1)/e;
$given =~ s/([- ].)/uc($1)/e;
}
if( $ENV{sn} )
{
$family = lc( $ENV{sn} );
$family =~ s/^(.)/uc($1)/e;
$family =~ s/([- ].)/uc($1)/e;
}

return unless EPrints::Utils::is_set( $username );

my $user = $session->user_by_username( $username ); # relying on this to be case insensitive

if( !defined $user )
{
my $usertype = 'user';
$user = EPrints::DataObj::User::create( $session, $usertype );
$user->set_value( "username", $username );
}
my $name = {
given => $given,
family => $family,
};
$user->set_value( "name", $name );
$user->set_value( "email", $email );
$user->commit;
return $user;
}

== 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].

* [https://docs.openathens.net/display/public/TPA/Sign+in+to+a+generic+application+using+OpenAthens#SignintoagenericapplicationusingOpenAthens-SetupthecustomSAMLresourceinOpenAthens Instructions of connection a Shibboleth Service Provider with OpenAthens]

[[Category:Authentication]]

Shibboleth

2025-01-21T14:20:27Z

Ejo1f20: typo

{{Manual}}
'''This page details how to install and integrate Shibboleth with EPrints 3.3.x or 3.4.x on a CentOS 7 operating system.''' The process should be fairly similar for other comparable Red Hat based Linux distributions such as RHEL 7 and Fedora 21/22. These instructions should also be generally applicable to later versions of RHEL-based Linux (e.g. Rocky Linux 8, Red Hat Enterprise Linux 9, etc.). However, they ma be somewhat different for Debian-based Linux, such as Ubuntu and Debian itself and other Linux distributions. Typically, this will 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 (if you need this for a different RHEL-based Linux distribution fill in the form at https://shibboleth.net/downloads/service-provider/latest/RPMS/):
root> wget -O /etc/yum.repos.d/shibboleth.repo https://shibboleth.net/cgi-bin/sp_repo.cgi?platform=CentOS_7

* Now you can use 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 type '''y''' and press enter.

* Once you have done that, test that '''shibd''' has no issues:
root> LD_LIBRARY_PATH=/opt/shibboleth/lib64 shibd -t

* ''shibd -t'' should return a couple of warning, like those listed below. These are due to it not yet being configured.
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. You may also want ensure Shibboleth starts at boot using '''systemctl enable'''
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
root> systemctl enable shibd.service

== Configuring Shibboleth ==
* Replace '''/etc/shibboleth/shibboleth2.xml''' with the following. Substitute '''foo.eprints.org''' for the hostname of your EPrints repository, '''https://shib.foo.example.org/idp/shibboleth''' with the entity ID for you Shibboleth IdP and '''foo''' in the pathname of files with the name or your repository (e.g. ''foo/attribute-map.xml'' becomes ''myrepo/attribute-map.xml''). '''(This configuration is intended for Shibboleth SP version 2.x and is liable to cause deprecation warnings if you have installed a recent version of Shibboleth from a package repository. [[Shibboleth/3.x|Here is a default shibboleth2.xml configuration for Shibboleth 3.x]]).'''

<SPConfig xmlns="urn:mace:shibboleth:3.0:native:sp:config"
xmlns:conf="urn:mace:shibboleth:3.0:native:sp:config"
clockSkew="180">

<ApplicationDefaults entityID="https://foo.eprints.org/shibboleth"
REMOTE_USER="eppn subject-id pairwise-id persistent-id"
cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">

<Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
checkAddress="false" handlerSSL="true" cookieProps="https"
redirectLimit="exact">
<SSO entityID="https://shib.foo.example.org/idp/shibboleth">SAML2</SSO>
<Logout>SAML2 Local</Logout>
<LogoutInitiator type="Admin" Location="/Logout/Admin" acl="127.0.0.1 ::1" />
<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" path="foo/idp-metadata.xml"/>
<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="foo/attribute-map.xml"/>
<AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
<CredentialResolver type="File" use="signing" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>
<CredentialResolver type="File" use="encryption" 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 hostname.
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.old sp-key.pem

* Check that '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/foo/''' still have the owner and group '''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

* Run '''metagen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository hostname. You will ultimately need to send the output of this to the person managing the Shibboleth IdP server with which you want to register your EPrints repository as a service.
root> cd /etc/shibboleth
root> ./metagen.sh -ALO -c foo/sp-cert.pem -h foo.eprints.org -e https://foo.eprints.org/shibboleth > foo/sp_metadata.xml

* Modify ''' foo/sp_metadata.xml''' to add in the namepace definitions by separately changing the <code>md:EntityDescriptor</code> and <code>ds:KeyInfo</code> lines as follows from:
<md:EntityDescriptor entityID="https://for.eprints.org/shibboleth">
...
...
<ds:KeyInfo>
to:
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://for.eprints.org/shibboleth">
...
...
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

* 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

=== Using Remote IdP Metatdata ===

As IdP Metadata may expire, you may want to use the remote metadata URL rather than a local copy. This is what you need to do to switch to using remote IdP metadata:

* Edit the '''MetadataProvider''' line to something like the following. The reloadInterval is best set to 7200 but this can be set less frequently:

<MetadataProvider type="XML" url="https://shib.foo.example.org/idp/metadata.xml" backingFilePath="foo/idp-metadata.xml" reloadInterval="7200"/>

* Make sure the reloadInterval is appropriate for the IdP metadata you are downloading. If you have large metadata file,(e.g. from a federated metadata service containing metadata for other IdPs), then it may be better to set this higher than the default. However, the configuration checker may warn you that your reload interval is too long, so you may have to choose to ignore this, if you want to avoid downloading a large federated metadata file too often.

* Make sure that the directory '''/etc/shibboleth/foo/''' and '''/etc/shibboleth/foo/idp-metadata.xml''' if it already exists) are owned by '''shibd''':

chown shibd:shibd /etc/shibboleth/foo/
chown shibd:shibd /etc/shibboleth/foo/idp-metadata.xml

* To test Shibboleth you will need to make sure your '''LD_LIBRARY_PATH''' is set the same as shibd would have when started using ''systemctl shibd start''. This should return the message: ''overall configuration is loadable, check console for non-fatal problems''.

LD_LIBRARY_PATH=/opt/shibboleth/lib64:$LD_LIBRARY_PATH shibd -t

* The above message is because it is now advised not to leave the MetadataGenerator enabled unnecessarily. However, whilst you are setting up Shibboleth, it is useful to have the metadata generator, save you needing to build your own Service Provider metadata file to register with your Identity Provider. Later on you can comment out the MetadataGenerator line to stop getting this warning message.

* Now you can restart '''shibd''' properly:

systemctl restart shibd

== 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 "<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

* 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>
<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 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.

== Troubleshooting ==

=== Apache Configuration Issues ===
==== Apache 2.2 (and lower) Configuration for EPrints Shibboleth Integration ====
* Similarly to the instructions for Apache 2.4 and above, place the slightly different following configuration after the '''Include''' line for ''apache_ssl/foo.conf'', (substituting '''foo''' for your archive's name):

Alias /shibboleth /opt/eprints3/archives/foo/shibboleth
<Directory "/opt/eprints3/archives/foo/shibboleth">
SetHandler perl-script
PerlHandler ModPerl::Registry
PerlSendHeader Off
Options ExecCGI FollowSymLinks

AuthType shibboleth
ShibRequireSession On
require valid-user
</Directory>

<Location /cgi/shibboleth>
AuthType shibboleth
ShibRequireSession On
require valid-user
</Location>

=== Shibboleth Configuration Issues ===
==== With attribute-map.xml ====
When authenticating using Shibboleth to login to EPrints you may see the following line in '''/var/log/shibboleth.shibd.log'''

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: urn:mace:dir:attribute-def:department

In some cases this might not be an issue, as EPrints does not necessarily to make use of all the attributes returned by the IdP but without a mapping in attribute-map.xml. In this case '''urn:mace:dir:attribute-def:department''' is not by default needed by EPrints to create/update a user account. However, values like '''sn''', '''givenName''' and '''mail''' are but if you have used the attribute-map.xml provided later on the page you should not see a line like above in '''shibd.log'''. In some cases you may still see an line like this in the log even if you think you have defined the attribute. The line below demonstrate two known issues:

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: givenName, Format:urn:oasis:names:tc:SAML:2.0:attrname-format:basic

# The attribute itself has no namespace it is just ''''givenName''' rather than '''urn:mace:dir:attribute-def:givenName'''
# The attribute has a format that most also be defined in the attribute-map.xml attribute.

Below shows how to both include the format, which is required for the attribute to be successful mapped. As well as define the name of the attribute without a namespace:

<Attribute name="givenName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>

A typical Shibboleth IdP would have both a namespaced attribute name and would not apply a format to an attribute that is a simple text string. Therefore it is worth enquiring with the IdP provider if either of these two happen to be the case.

==== With idp-metadata.xml ====
If you want to be able extract scoped attributes (e.g. '''eduPersonPrincipalName''' otherwise described as '''eppn'''). Then you will need to ensure that the expected scope of this attribute, (effectively the domain part in eduPersonPrincipalName is the scope or one of the scopes in the idp-metadata.xml you downloaded from the Shibboleth IdP. For example if the '''eduPersonPrincipalName''' is '''bar@foo.ac.uk'''. Then the following should be defined in idp-metadata.xml ('''N.B. the namespace abbreviations (md: and shibmd:) may be different for the IdP you are working with'''):

<md:Extensions>
<shibmd:Scope regexp="false">foo.ac.uk</shibmd:Scope>
</md:Extensions>

=== Login Issues ===
To be added.

== Customisation ==

=== Shibboleth /etc/shibboleth/foo/attribute-map.xml config ===
This is adapted from the default '''attribute-map.xml''' provided when the Shibboleth SP package is installed to only include the attribute subsequently used by EPrints Shibboleth Perl script that can be found below. Namely:

{| border="1" cellpadding="10" cellspacing="0"
!Field name
!Field description
!SAML v1.1 attribute URN
!SAMLv2 attribute URN
|-
|eppn
|Edu Person Principal Name
|urn:mace:dir:attribute-def:eduPersonPrincipalName
|urn:oid:1.3.6.1.4.1.5923.1.1.1.6
|-
|sn
|Surname
|urn:mace:dir:attribute-def:sn
|urn:oid:2.5.4.4
|-
|givenName
|Given (first) name(s)
|urn:mace:dir:attribute-def:givenName
|urn:oid:2.5.4.42
|-
|mail
|Email address
|urn:mace:dir:attribute-def:mail
|urn:oid:0.9.2342.19200300.100.1.3
|-
|}

You may wish to refer to the default '''attribute-map.xml''' is you want to use other attributes.

<Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>
<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>

<Attribute name="urn:mace:dir:attribute-def:sn" id="sn"/>
<Attribute name="urn:mace:dir:attribute-def:givenName" id="givenName"/>
<Attribute name="urn:mace:dir:attribute-def:mail" id="mail"/>

<Attribute name="urn:oid:2.5.4.4" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="sn"/>
<Attribute name="urn:oid:2.5.4.42" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>
<Attribute name="urn:oid:0.9.2342.19200300.100.1.3" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="mail"/>

</Attributes>

=== EPrints /shibboleth/login script with user account creation ===
This is the standard EPrints Shibboleth login script. It makes a number of assumptions:
# That accounts should be created if they do not already exist for a particular user.
# That you wish to create a standard user account (not an editor administrator) account.
# That the Shibboleth IdP provides all the attributes (eduPersonPrinicpalName (seen as eppn), sn, givenName and mail) required.

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, $given, $family, $email) = (undef, "", "", "");

if( $ENV{eppn} )
{
( $username ) = split( /@/, $ENV{eppn}, 2);
$username = lc( $username );
}
$email = $ENV{mail} if $ENV{mail};
if( $ENV{givenName} )
{
$given = lc( $ENV{givenName} );
$given =~ s/^(.)/uc($1)/e;
$given =~ s/([- ].)/uc($1)/e;
}
if( $ENV{sn} )
{
$family = lc( $ENV{sn} );
$family =~ s/^(.)/uc($1)/e;
$family =~ s/([- ].)/uc($1)/e;
}

return unless EPrints::Utils::is_set( $username );

my $user = $session->user_by_username( $username ); # relying on this to be case insensitive

if( !defined $user )
{
my $usertype = 'user';
$user = EPrints::DataObj::User::create( $session, $usertype );
$user->set_value( "username", $username );
}
my $name = {
given => $given,
family => $family,
};
$user->set_value( "name", $name );
$user->set_value( "email", $email );
$user->commit;
return $user;
}

== 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].

* [https://docs.openathens.net/display/public/TPA/Sign+in+to+a+generic+application+using+OpenAthens#SignintoagenericapplicationusingOpenAthens-SetupthecustomSAMLresourceinOpenAthens Instructions of connection a Shibboleth Service Provider with OpenAthens]

[[Category:Authentication]]

Shibboleth

2025-01-21T14:19:49Z

Ejo1f20:

{{Manual}}
'''This page details how to install and integrate Shibboleth with EPrints 3.3.x or 3.4.x on a CentOS 7 operating system.''' The process should be fairly similar for other comparable Red Hat based Linux distributions such as RHEL 7 and Fedora 21/22. These instructions should also be generally application to later versions of RHEL-based Linux (e.g. Rocky Linux 8, Red Hat Enterprise Linux 9, etc.). However, they ma be somewhat different for Debian-based Linux, such as Ubuntu and Debian itself and other Linux distributions. Typically, this will 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 (if you need this for a different RHEL-based Linux distribution fill in the form at https://shibboleth.net/downloads/service-provider/latest/RPMS/):
root> wget -O /etc/yum.repos.d/shibboleth.repo https://shibboleth.net/cgi-bin/sp_repo.cgi?platform=CentOS_7

* Now you can use 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 type '''y''' and press enter.

* Once you have done that, test that '''shibd''' has no issues:
root> LD_LIBRARY_PATH=/opt/shibboleth/lib64 shibd -t

* ''shibd -t'' should return a couple of warning, like those listed below. These are due to it not yet being configured.
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. You may also want ensure Shibboleth starts at boot using '''systemctl enable'''
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
root> systemctl enable shibd.service

== Configuring Shibboleth ==
* Replace '''/etc/shibboleth/shibboleth2.xml''' with the following. Substitute '''foo.eprints.org''' for the hostname of your EPrints repository, '''https://shib.foo.example.org/idp/shibboleth''' with the entity ID for you Shibboleth IdP and '''foo''' in the pathname of files with the name or your repository (e.g. ''foo/attribute-map.xml'' becomes ''myrepo/attribute-map.xml''). '''(This configuration is intended for Shibboleth SP version 2.x and is liable to cause deprecation warnings if you have installed a recent version of Shibboleth from a package repository. [[Shibboleth/3.x|Here is a default shibboleth2.xml configuration for Shibboleth 3.x]]).'''

<SPConfig xmlns="urn:mace:shibboleth:3.0:native:sp:config"
xmlns:conf="urn:mace:shibboleth:3.0:native:sp:config"
clockSkew="180">

<ApplicationDefaults entityID="https://foo.eprints.org/shibboleth"
REMOTE_USER="eppn subject-id pairwise-id persistent-id"
cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">

<Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
checkAddress="false" handlerSSL="true" cookieProps="https"
redirectLimit="exact">
<SSO entityID="https://shib.foo.example.org/idp/shibboleth">SAML2</SSO>
<Logout>SAML2 Local</Logout>
<LogoutInitiator type="Admin" Location="/Logout/Admin" acl="127.0.0.1 ::1" />
<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" path="foo/idp-metadata.xml"/>
<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="foo/attribute-map.xml"/>
<AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
<CredentialResolver type="File" use="signing" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>
<CredentialResolver type="File" use="encryption" 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 hostname.
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.old sp-key.pem

* Check that '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/foo/''' still have the owner and group '''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

* Run '''metagen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository hostname. You will ultimately need to send the output of this to the person managing the Shibboleth IdP server with which you want to register your EPrints repository as a service.
root> cd /etc/shibboleth
root> ./metagen.sh -ALO -c foo/sp-cert.pem -h foo.eprints.org -e https://foo.eprints.org/shibboleth > foo/sp_metadata.xml

* Modify ''' foo/sp_metadata.xml''' to add in the namepace definitions by separately changing the <code>md:EntityDescriptor</code> and <code>ds:KeyInfo</code> lines as follows from:
<md:EntityDescriptor entityID="https://for.eprints.org/shibboleth">
...
...
<ds:KeyInfo>
to:
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://for.eprints.org/shibboleth">
...
...
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

* 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

=== Using Remote IdP Metatdata ===

As IdP Metadata may expire, you may want to use the remote metadata URL rather than a local copy. This is what you need to do to switch to using remote IdP metadata:

* Edit the '''MetadataProvider''' line to something like the following. The reloadInterval is best set to 7200 but this can be set less frequently:

<MetadataProvider type="XML" url="https://shib.foo.example.org/idp/metadata.xml" backingFilePath="foo/idp-metadata.xml" reloadInterval="7200"/>

* Make sure the reloadInterval is appropriate for the IdP metadata you are downloading. If you have large metadata file,(e.g. from a federated metadata service containing metadata for other IdPs), then it may be better to set this higher than the default. However, the configuration checker may warn you that your reload interval is too long, so you may have to choose to ignore this, if you want to avoid downloading a large federated metadata file too often.

* Make sure that the directory '''/etc/shibboleth/foo/''' and '''/etc/shibboleth/foo/idp-metadata.xml''' if it already exists) are owned by '''shibd''':

chown shibd:shibd /etc/shibboleth/foo/
chown shibd:shibd /etc/shibboleth/foo/idp-metadata.xml

* To test Shibboleth you will need to make sure your '''LD_LIBRARY_PATH''' is set the same as shibd would have when started using ''systemctl shibd start''. This should return the message: ''overall configuration is loadable, check console for non-fatal problems''.

LD_LIBRARY_PATH=/opt/shibboleth/lib64:$LD_LIBRARY_PATH shibd -t

* The above message is because it is now advised not to leave the MetadataGenerator enabled unnecessarily. However, whilst you are setting up Shibboleth, it is useful to have the metadata generator, save you needing to build your own Service Provider metadata file to register with your Identity Provider. Later on you can comment out the MetadataGenerator line to stop getting this warning message.

* Now you can restart '''shibd''' properly:

systemctl restart shibd

== 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 "<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

* 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>
<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 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.

== Troubleshooting ==

=== Apache Configuration Issues ===
==== Apache 2.2 (and lower) Configuration for EPrints Shibboleth Integration ====
* Similarly to the instructions for Apache 2.4 and above, place the slightly different following configuration after the '''Include''' line for ''apache_ssl/foo.conf'', (substituting '''foo''' for your archive's name):

Alias /shibboleth /opt/eprints3/archives/foo/shibboleth
<Directory "/opt/eprints3/archives/foo/shibboleth">
SetHandler perl-script
PerlHandler ModPerl::Registry
PerlSendHeader Off
Options ExecCGI FollowSymLinks

AuthType shibboleth
ShibRequireSession On
require valid-user
</Directory>

<Location /cgi/shibboleth>
AuthType shibboleth
ShibRequireSession On
require valid-user
</Location>

=== Shibboleth Configuration Issues ===
==== With attribute-map.xml ====
When authenticating using Shibboleth to login to EPrints you may see the following line in '''/var/log/shibboleth.shibd.log'''

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: urn:mace:dir:attribute-def:department

In some cases this might not be an issue, as EPrints does not necessarily to make use of all the attributes returned by the IdP but without a mapping in attribute-map.xml. In this case '''urn:mace:dir:attribute-def:department''' is not by default needed by EPrints to create/update a user account. However, values like '''sn''', '''givenName''' and '''mail''' are but if you have used the attribute-map.xml provided later on the page you should not see a line like above in '''shibd.log'''. In some cases you may still see an line like this in the log even if you think you have defined the attribute. The line below demonstrate two known issues:

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: givenName, Format:urn:oasis:names:tc:SAML:2.0:attrname-format:basic

# The attribute itself has no namespace it is just ''''givenName''' rather than '''urn:mace:dir:attribute-def:givenName'''
# The attribute has a format that most also be defined in the attribute-map.xml attribute.

Below shows how to both include the format, which is required for the attribute to be successful mapped. As well as define the name of the attribute without a namespace:

<Attribute name="givenName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>

A typical Shibboleth IdP would have both a namespaced attribute name and would not apply a format to an attribute that is a simple text string. Therefore it is worth enquiring with the IdP provider if either of these two happen to be the case.

==== With idp-metadata.xml ====
If you want to be able extract scoped attributes (e.g. '''eduPersonPrincipalName''' otherwise described as '''eppn'''). Then you will need to ensure that the expected scope of this attribute, (effectively the domain part in eduPersonPrincipalName is the scope or one of the scopes in the idp-metadata.xml you downloaded from the Shibboleth IdP. For example if the '''eduPersonPrincipalName''' is '''bar@foo.ac.uk'''. Then the following should be defined in idp-metadata.xml ('''N.B. the namespace abbreviations (md: and shibmd:) may be different for the IdP you are working with'''):

<md:Extensions>
<shibmd:Scope regexp="false">foo.ac.uk</shibmd:Scope>
</md:Extensions>

=== Login Issues ===
To be added.

== Customisation ==

=== Shibboleth /etc/shibboleth/foo/attribute-map.xml config ===
This is adapted from the default '''attribute-map.xml''' provided when the Shibboleth SP package is installed to only include the attribute subsequently used by EPrints Shibboleth Perl script that can be found below. Namely:

{| border="1" cellpadding="10" cellspacing="0"
!Field name
!Field description
!SAML v1.1 attribute URN
!SAMLv2 attribute URN
|-
|eppn
|Edu Person Principal Name
|urn:mace:dir:attribute-def:eduPersonPrincipalName
|urn:oid:1.3.6.1.4.1.5923.1.1.1.6
|-
|sn
|Surname
|urn:mace:dir:attribute-def:sn
|urn:oid:2.5.4.4
|-
|givenName
|Given (first) name(s)
|urn:mace:dir:attribute-def:givenName
|urn:oid:2.5.4.42
|-
|mail
|Email address
|urn:mace:dir:attribute-def:mail
|urn:oid:0.9.2342.19200300.100.1.3
|-
|}

You may wish to refer to the default '''attribute-map.xml''' is you want to use other attributes.

<Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>
<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>

<Attribute name="urn:mace:dir:attribute-def:sn" id="sn"/>
<Attribute name="urn:mace:dir:attribute-def:givenName" id="givenName"/>
<Attribute name="urn:mace:dir:attribute-def:mail" id="mail"/>

<Attribute name="urn:oid:2.5.4.4" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="sn"/>
<Attribute name="urn:oid:2.5.4.42" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>
<Attribute name="urn:oid:0.9.2342.19200300.100.1.3" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="mail"/>

</Attributes>

=== EPrints /shibboleth/login script with user account creation ===
This is the standard EPrints Shibboleth login script. It makes a number of assumptions:
# That accounts should be created if they do not already exist for a particular user.
# That you wish to create a standard user account (not an editor administrator) account.
# That the Shibboleth IdP provides all the attributes (eduPersonPrinicpalName (seen as eppn), sn, givenName and mail) required.

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, $given, $family, $email) = (undef, "", "", "");

if( $ENV{eppn} )
{
( $username ) = split( /@/, $ENV{eppn}, 2);
$username = lc( $username );
}
$email = $ENV{mail} if $ENV{mail};
if( $ENV{givenName} )
{
$given = lc( $ENV{givenName} );
$given =~ s/^(.)/uc($1)/e;
$given =~ s/([- ].)/uc($1)/e;
}
if( $ENV{sn} )
{
$family = lc( $ENV{sn} );
$family =~ s/^(.)/uc($1)/e;
$family =~ s/([- ].)/uc($1)/e;
}

return unless EPrints::Utils::is_set( $username );

my $user = $session->user_by_username( $username ); # relying on this to be case insensitive

if( !defined $user )
{
my $usertype = 'user';
$user = EPrints::DataObj::User::create( $session, $usertype );
$user->set_value( "username", $username );
}
my $name = {
given => $given,
family => $family,
};
$user->set_value( "name", $name );
$user->set_value( "email", $email );
$user->commit;
return $user;
}

== 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].

* [https://docs.openathens.net/display/public/TPA/Sign+in+to+a+generic+application+using+OpenAthens#SignintoagenericapplicationusingOpenAthens-SetupthecustomSAMLresourceinOpenAthens Instructions of connection a Shibboleth Service Provider with OpenAthens]

[[Category:Authentication]]

How to configure DKIM email verification (using sendmail on Rocky9)

2024-07-25T08:28:59Z

Ejo1f20:

__TOC__

== Notes ==

These instructions have been tested on CentOS7 and Rocky9 both of which using sendmail (not postfix). You will likely be able to adapt these instructions fairly easily to suit your operating system and mail transfer program.

== Steps ==

'''As eprints user'''

1. Create a directory to store the keys

mkdir /opt/eprints3/archives/<REPO-ID>/dkim

'''As root user'''

1. Install the opendkim libraries

dnf install opendkim opendkim-tools

2. Open the opendkim config file and change the following lines

vim /etc/opendkim.conf

2. a. Change

Mode V
to
Mode sv

2. b. Remove comments from the following lines:

KeyTable /etc/opendkim/KeyTable
SigningTable refile:/etc/opendkim/SigningTable
ExternalIgnoreList refile:/etc/opendkim/TrustedHosts
InternalHosts refile:/etc/opendkim/TrustedHosts

2. c. Add the following lines (the DOMAIN is the domain which our server sending email on behalf of)

Domain <DOMAIN>
RequireSafeKeys False

2. d. Replace the Socket declaration with the following line (it should be commented out above the declaration being used)

Socket inet:8891@localhost

3. Modify /etc/opendkim/KeyTable, to add the following line

default._domainkey.<DOMAIN> <DOMAIN>:default:/opt/eprints3/archives/<REPOID>/dkim/default.private

'''example:''' `default._domainkey.eprints-hosting.org eprints-hosting.org:default:/opt/eprints3/archives/repoid/dkim/default.private`

4. Modify /etc/opendkim/SigningTable, to add the following line

*@<DOMAIN> default._domainkey.<DOMAIN>

'''example:''' `*@eprints-hosting.org default._domainkey.eprints-hosting.org`

5. Modify /etc/opendkim/TrustedHosts, to add the following line

*.<DOMAIN>

'''example:''' *.eprints-hosting.org

6. Generate the keypair

sudo opendkim-genkey -b 1024 -d <DOMAIN> -D /opt/eprints3/archives/<REPO-ID>/dkim<DOMAIN> -s default -v

7. Change ownership and permissions

sudo chown opendkim:opendkim /opt/eprints3/archives/<REPO-ID>/dkim/* -R
sudo chmod 660 /opt/eprints3/archives/<REPO-ID>/dkim/*

8. Send the txt public key to whoever has access to the DNS records, probably their IT team

cat /etc/opendkim/keys/<DOMAIN>/default.txt

It should look something like this.

"v=DKIM1; k=rsa; " "p=REALLY-LONG-HASH-VALUE/HASH-VALUE/HASH-VALUE"

9. Start opendkim

systemctl start opendkim; systemctl enable opendkim

10. Make sure it is running with the following commands

service opendkim status
This should say running.

ps -aux | grep dkim
The opendkim process should be running: "/usr/sbin/opendkim -f -x /etc/opendkim.con"

netstat -nap | grep 8891
This command should show that opendkim is listening on localhost port 8819

11. Sendmail Configuration

11. a. Modify sendmail.mc, append the following line

INPUT_MAIL_FILTER(`opendkim', `S=inet:8891@localhost')

11. b. re-make sendmail.cf, restart sendmail.

/etc/mail/make
systemctl restart sendmail

12. Send a test email

echo “Subject: DKIM testing” | sendmail test-recipient@address.email

13. If the test email has worked, test again using the web interface admin tool "Send Test Email"

14. Debug any issues using

tail -F /var/log/maillog*

How to configure DKIM email verification (using sendmail on Rocky9)

2024-07-25T08:26:52Z

Ejo1f20: Created page with "== Manual Steps == '''As eprints user''' 1. Create a directory to store the keys mkdir /opt/eprints3/archives/<REPO-ID>/dkim '''As root user''' 1. Install the opendkim l..."

== Manual Steps ==

'''As eprints user'''

1. Create a directory to store the keys

mkdir /opt/eprints3/archives/<REPO-ID>/dkim

'''As root user'''

1. Install the opendkim libraries

dnf install opendkim opendkim-tools

2. Open the opendkim config file and change the following lines

vim /etc/opendkim.conf

2. a. Change

Mode V
to
Mode sv

2. b. Remove comments from the following lines:

KeyTable /etc/opendkim/KeyTable
SigningTable refile:/etc/opendkim/SigningTable
ExternalIgnoreList refile:/etc/opendkim/TrustedHosts
InternalHosts refile:/etc/opendkim/TrustedHosts

2. c. Add the following lines (the DOMAIN is the domain which our server sending email on behalf of)

Domain <DOMAIN>
RequireSafeKeys False

2. d. Replace the Socket declaration with the following line (it should be commented out above the declaration being used)

Socket inet:8891@localhost

3. Modify /etc/opendkim/KeyTable, to add the following line

default._domainkey.<DOMAIN> <DOMAIN>:default:/opt/eprints3/archives/<REPOID>/dkim/default.private

'''example:''' `default._domainkey.eprints-hosting.org eprints-hosting.org:default:/opt/eprints3/archives/repoid/dkim/default.private`

4. Modify /etc/opendkim/SigningTable, to add the following line

*@<DOMAIN> default._domainkey.<DOMAIN>

'''example:''' `*@eprints-hosting.org default._domainkey.eprints-hosting.org`

5. Modify /etc/opendkim/TrustedHosts, to add the following line

*.<DOMAIN>

'''example:''' *.eprints-hosting.org

6. Generate the keypair

sudo opendkim-genkey -b 1024 -d <DOMAIN> -D /opt/eprints3/archives/<REPO-ID>/dkim<DOMAIN> -s default -v

7. Change ownership and permissions

sudo chown opendkim:opendkim /opt/eprints3/archives/<REPO-ID>/dkim/* -R
sudo chmod 660 /opt/eprints3/archives/<REPO-ID>/dkim/*

8. Send the txt public key to whoever has access to the DNS records, probably their IT team

cat /etc/opendkim/keys/<DOMAIN>/default.txt

It should look something like this.

"v=DKIM1; k=rsa; " "p=REALLY-LONG-HASH-VALUE/HASH-VALUE/HASH-VALUE"

9. Start opendkim

systemctl start opendkim; systemctl enable opendkim

10. Make sure it is running with the following commands

service opendkim status
This should say running.

ps -aux | grep dkim
The opendkim process should be running: "/usr/sbin/opendkim -f -x /etc/opendkim.con"

netstat -nap | grep 8891
This command should show that opendkim is listening on localhost port 8819

11. Sendmail Configuration

11. a. Modify sendmail.mc, append the following line

INPUT_MAIL_FILTER(`opendkim', `S=inet:8891@localhost')

11. b. re-make sendmail.cf, restart sendmail.

/etc/mail/make
systemctl restart sendmail

12. Send a test email

echo “Subject: DKIM testing” | sendmail test-recipient@address.email

13. If the test email has worked, test again using the web interface admin tool "Send Test Email"

14. Debug any issues using

tail -F /var/log/maillog*

Manual

2024-07-25T08:22:19Z

Ejo1f20: /* How-to Guides */

__NOTOC__
See the [[Main Page]] for other areas of this wiki.

* [[Introduction|Introduction to EPrints]] and [[History|History of EPrints]]

<table cellpadding="10"><tr><td width="33%" valign="top">
= Releases =
{{releasenotes}}
''See also the note on [[EPrints Version Numbering]]''

= Download =
{{Download}}

= Installation =
* [[Recommended Platforms]]
* [[Required software]]
* Install Guides
** [[Installing EPrints on RHEL/Fedora/CentOS]]
*** Primarily RedHat Enterprise Linux (RHEL) and CentOS 7 and 8.
*** Guides for installing from RPM package and from source.
** [[Installing EPrints on Debian/Ubuntu]]
*** Primarily Ubuntu 18.04 LTS and 20.04 LTS.
*** Guides for installing from Deb package and from source.
* [[Installation|Generic EPrints installation instructions]]
* [[How to use EPrints with HTTPS]]
** [[Setting up HTTPS using Let's Encrypt]]
** [[HTTPS-only and HSTS]]
* [[Installing EPrints using Docker]]

= Post Installation =
* [[Getting Started with EPrints 3]]

= Maintenance =
* [[Backups]]
* [[Generate Scripts]]
* [[Alerts]]
* [[Log Files]]
* [[Automating your maintenance]]
* [[Troubleshooting]]
* [[Apache Hardening]]
</td>

<td width="33%" valign="top" style="border-left: solid 1px #ccc; border-right: solid 1px #ccc;">

= Training Materials =
* [[:Category:Training Video|EPrints Training Course]]
* [http://www.eprints.org/software/training/ Training materials] provided by EPrints Services.

= How-to Guides =
''[http://en.wikipedia.org/wiki/Howto What is a how-to?]

* [[:Category:Howto|Orientation/Overview]] <span style="color: #f94; font-size: 130%">(Start here)</span>
** [[Configuration orientation|New to EPrints 3?]] - ''before diving into the how-tos, take some time to read through this brief orientation guide and familiarise yourself with the EPrints configuration landscape ...''
* [[Front Page Warning | Removing the Front Page Warning]] - Your first go at branding
* [[Branding with confidence]] - ''one of the most common EPrints customisations is to add your own institution's branding and "look and feel" to the interface...''
** [[Branding, the next level]] - ''how to completely change the interface to your own design''
* [[OAI]]
* [[Adding new views]]
* Workflow
* Deposit Types
** [[Removing types]]
* Metadata
* Subjects (fold in with Organisation Hierarchy under "controled vocabularies")
* [[EPrints_3_Organisation_Hierarchy|Organisation Hierarchy]] - ''how to put your own organisation's Hierarchy into EPrints 3''
* Searches
* [[Autocompletion and Authority Files (Romeo Autocomplete)]] - ''add autocomplete functionality to the Publication Title input field based on an authority file downloaded from EPrints Romeo...''
* [[Create Export Plugins]] - ''create a Perl Module that will export your data...''
* [[Login-Only Repository]] - ''require a username and password to access all pages (including search, browse, and the front page)...''
* [[Change Deposit Status in Bulk]] - ''move a large number of deposits from inbox to archive.''
* [[SWORD]] - ''how to configure the SWORD protocol on EPrints.''
* [[Custom handlers]] - ''how to add a custom handler for intergration with third-party applications.''
* [[User Deposit Agreement]] - ''How to add a user deposit agreement to the workflow.''
* [[ORCID]]
** [[Import From ORCID]]
* Javascript
** [[Include Javascript in the workflow]]
* DKIM email verification
** [[How to configure DKIM email verification (using sendmail on Rocky9)]]

= How to contribute =
There's a number of different ways you can contribute to the EPrints project. This section covers all the ones we can think of...

Always make an entry on http://files.eprints.org/ for your contribution, even if you don't upload the files. This will make it the one-stop place for people to find EPrints extensions.

* [[:Category:Documentation Needed| Create some of the missing documentation]]
* [[Contribute: Plugins | Plugins]]
* [[Contribute: Scripts | Scripts]]
* [[Contribute: Themes | Themes]]
* [[Contribute: Translations | Translations]]
* [[Contribute: Other | Other neighbourly things to do]]
* [[Extension Packages]]

= Misc =
* [[Preservation Support]] in EPrints 3
* [[:Category:Languages|Language support and translations]]
</td><td valign="top" width="33%">

= Technical Reference =
* [[EPrints Directory Structure]] - How code and configuation files are organised.
* [[EPrints Glossary]] - A listing of terminology used within EPrints.
* [[User Menu]] - Explaining the menu options available to an EPrints user.
* [[Admin|Admin Menu]] - Explaining the tools available to a repository administrator.
* [[Metadata]] - configuring metadata fields.
* [[Archives/ARCHIVEID/cfg/|Repository Configuration]]
* [[XML Configuration]] Files
** [[EPScript]] - documentation for the EP3 Scripting language (for use in citations and workflow files).
** [[EPrints Control Format]] - the structure used to embed EPScript in an XML configuration file.
** [[Citation Format]]
** [[Workflow Format]] - the structure of the EP3 workflow files
** [[Phrase Format]]
** [[Template Format]]
** [[XPAGE Format]]
* [[XML Export Format]]
* EPrints data structure
** of the software
** of the database (relating the dataobjects to each other using eprints fields)
* [[Data Object]]s and data sets
** The [[EPrint Object]]
** The [[User Object]]
** The [[Document Object]]
** The [[Subject Object]]
** The [[Saved Search Object]]
** The [[History Object]]
** The [[Access Object]]
** The [[Request Object]]
* [[:Category:Plugins|Plugins]]
** [[Create Export Plugins|Export]]
** Import
** [[Screen Plugins|Screen]]
* [[Autocompletion]]
** [[Understanding IDs in Workflow Forms]]
* [[API]]
* [[Dynamic Template System]]
* [[Config Options by File]]

= The EPrints Bazaar =
* [[:Category:EPrints_Bazaar|The EPrints Bazaar]] (Start Here)
* The [[EPM Specification]]
* [[:Category:Bazaar_Package|Bazaar Packages]]

</td></tr></table>

IRStats2

2024-02-05T11:22:25Z

Ejo1f20: /* Embedding Stats on Abstract Pages */

[[Category:API]]
[[Category:IRStats]]
[[Category:Plugins]]
[[Category:Bazaar_Package]]
[[Category:Eprints3.4]]
[[Category:Eprints3.3]]

=What is IRStats2?=
IRStats2 is a statistical framework for EPrints - It comes with some cool default tools and reports and it can also be customised to, for instance, add new metrics or data sets. It has a Javascript API to include stats on any pages you want.

IRStats2 is developed against EPrints 3.4 and 3.3 but it was written to also work on EPrints 3.2. However, as EPrints 3.2 is no longer supported there is likewise no support for running IRStats2 on EPrints 3.2.

=What's new in version 1.1?=
This new version includes a number of improvements to existing features such as easier deployment, faster database code, tool tips and improved browser detection, as well as a number of smaller tweaks and fixes.

It now also includes filtering to allow the blocking of web crawling robots as standard.

==Changes in 1.1, since 1.0.x==

=== Features ===
* IP based robot filtering and default values
* Adding an option to only show live items in the stats

=== Improvements ===
* Avoid using experimental perl code.(i.e. ~~ )
* Restructure to make epm deployment easier
* Tooltip help text for KeyFigures
* Optimisation for InnoDB
* CSV, JSON, XML saves file as instead of open directly in the browser
* Added missing libraries check (Date::Calc and Geo::IP) on bazaar installation page. resolves [https://github.com/eprints/irstats2/issues/10 #10]
* %IGNORE_LIST of words (stopwords) are very few and only in "en"
* Add support for transactions

=== Bug Fixes ===
* Stats::View::google::Graph lose first statistics [https://github.com/eprints/irstats2/issues/69 #69]
* Browser identification issue [https://github.com/eprints/irstats2/issues/66 #66]
* The title of Screen::IRStats2::Report should not change according to report you chose
* Avoid XSS vulnerability in some CGI output

=Installation=

==Dependencies==
* Geo::IP or Geo::IP::PurePerl
* Date::Calc

Both can usually be installed via your Linux package managers (apt-get, yum, ...) or via CPAN.

=== Debian/Ubuntu ===
apt-get install libgeo-ip-perl libdate-calc-perl

=== RedHat/CentOS/Fedora ===
yum install perl-Geo-IP perl-Date-Calce

=== CPAN ===
cpan Geo::IP Date::Calc

==EPrints 3.3 and 3.4==
IRStats2 can be installed directly via the Bazaar on EPrints 3.3 and 3.4.

===EPrints 3.3.11 (inc. 3.4.x) onwards===
Installing IRStats2 from the Bazaar is all you need to do. It is recommend that you restart Apache after doing so.

===EPrints 3.3.1 to 3.3.10===
You need to install IRStats2 from the Bazaar as above, but you also need to apply a few patches to enable the Google map showing the "Origins of downloads".

The patches relate to an incompatibility between the Prototype JS library (used by EPrints) and Google Charts (used by IRStats2). The two patches you need to apply are:

*[https://github.com/eprints/eprints/commit/f7a9088aae29b8732cb5d8edd83d17e94f069e63 Upgrade Prototype]
*[https://github.com/eprints/eprints/issues/130 Fix auto-completers]

==EPrints 3.2.x==
See [[IRStats2/EPrints 3.2]]

==Processing==
IRStats2 uses its own tables to manage statistics, which it populates from the EPrints access table (a table containing a row for every access to EPrints objects). Once installed, IRStats needs to process the full contents of this table. Processing works in two steps: the initial processing and then a daily incremental processing. Because the initial processing will take care of all your legacy "download" data, this can take a (very) long time. It may take a few days if your repository is very large, although more likely it will take a few hours.

For the initial processing, run, as the "eprints" user, the below command (and remember this may take a long time to complete). If you are running it from an SSH session, you may want to use the "screen" Linux utility to make sure your SSH session will persist.

<pre>
/opt/eprints3/archives/REPO_ID/bin/stats/process_stats REPO_ID --setup --verbose
</pre>

For the daily incremental processing, add the below line in cron. It is a good idea to let this run over-night when there is less traffic to your repository (note the redirections of output to /dev/null will make the script run silently).

<pre>
perl /opt/eprints3/archives/REPO_ID/bin/stats/process_stats REPO_ID 1>/dev/null 2>/dev/null
The two redirections to /dev/null forces the process to not output anything.
</pre>

=Viewing Stats=
The main IRStats2 dashboard is available at: http://yourrepo.url/cgi/stats/report

== Embedding Stats on Abstract Pages ==

Edit the EPrint Summary Page citation file (this can be done from the command line or the configuration editor) and add the following phrase near the bottom:

<epc:phrase ref="lib/irstats2:embedded:summary_page:eprint:downloads">
<epc:param name="eprintid"><epc:print expr="eprintid"/></epc:param>
</epc:phrase>

Then restart apache and regenerate the abstract pages.

=Configuration=
This section details how to configure IRStats2 and mostly relates to the file cfg/cfg.d/z_irstats2.pl.

It is recommended that you edit your changes in a separate file (e.g. zz_irstats2_local.pl - must be loaded AFTER z_irstats2.pl) as this will make Bazaar updates easier to apply.

==Datasets/Datatypes==
Since IRStats2 can handle any EPrints datasets (not just the 'access' dataset which records downloads), you can declare in the configuration which EPrints datasets to process. For each EPrints dataset configured, IRStats2 will pass on the records from the Database to each processing module. This is coupled to the Stats::Processor modules and you will see that, by default, IRStats2 processes:

*The "access" dataset with the associated Stats::Processor::Access modules
*The "eprint" dataset with the associated Stats::Processor::EPrint modules
*The "history" dataset with, as you have guessed, the Stats::Processor::History modules

Each module will provide specific datum, which is declared in the module itself. For instance, Stats::Processor::Access::Downloads provides us with the "downloads" and "views" data-types.

===Configuration example and options===

<pre>
access => {
filters => [ 'Robots', 'Repeat' ],
incremental => 1
}
</pre>

The only two options which can be used are:

*'''incremental''': 1 or 0 (default 1) - tells IRStats2 to incrementally process the DB records. Since IRStats2 data must be processed daily, this indicates whether you should reprocess the entire dataset every day. For downloads (ie. the "access" dataset), you only need to reprocess the daily downloads, there is no need to restart from 0. However, some metrics used for the "eprint" dataset requires the entire dataset to be re-processed daily, which is OK as the "eprint" dataset is usually much smaller than the "access" one.

*'''filters''': an array of Filters (default []) - tells IRStats2 to apply filters before processing the records. This is especially useful for "access" records where hits by robots/crawlers are usually removed. Filters are very similar to Processor modules, except that they must return a boolean to indicate whether to keep or to discard the record. If the record is kept then it is passed on to the related Processor modules.

Remember that if you want to process new datasets (e.g. "user") then you must write the associated Stats::Processor modules, otherwise nothing would happen.

==Sets==
A Set tells IRStats2 how to group data points and it is done via an existing ("eprint") meta-field. Each value of that set (in essence, the distinct values of the field) will become a set value you can use in IRStats2 to give you statistics on the value. For instance, you can get download stats by author or by item type. Both "author" and "item type" are sets. Most Set definitions are straight-forward to declare, with the exception of "creators" (a.k.a. "authors").

===Configuration example and options===
<pre>
{
'field' => 'divisions',
'groupings' => [ 'authors' ]
},
</pre>

This defines the Set "divisions" - if the divisions field reflects the hierarchical structure of your institution (as it should) then you can get stats per division/school/faculty. You can also get "Top publications" per division.

Here are all the options you may use when defining a Set:

*'''name''': (optional - default to 'field') - the name of the set
*'''field''': the "eprint" field to use to generate set values
*'''groupings''': (optional - default to []) - an ARRAY of set names to use as groupings. A new grouping, within a set, fills in the statement: "I want to be able to see Top Y per set". For instance for the set 'divisions' and the grouping 'authors': "I want to be able to see Top Authors per Divisions".
*'''anon''': (optional - default to ) - whether to make the set values anonymous (and hex MD5 is used instead). This is particularly useful when using authors' ID which is usually their email address (and you don't want to make these public).
*'''use_ids''': For compound fields only (especially for creators). Tell IRStats2 to use the "id" part to generate distinct set values. This is more accurate that using the "name" part only.
*'''id_field''': For compound fields only. The name of the "id" field - usually it is just "id", as in "creators_id".
*'''minimum_filter_length''': Used by the Set Finder on the Reports. If set, this only start searching for set values after the user has entered minimum_filter_length characters. Some sets can be large (esp. creators) and we do not really want to preload the potential 100's of thousands of authors names on the UI. Instead we ask the user to search for author's names.
*'''render_single_value''': A CODEREF that must return a DOM element. This will tell how to render a set value, if you do not wish to use the default renderers. The function will receive three variables: $repo, $setname and $setvalue.

Note that "eprint" is a built-in Set and should not be defined in the configuration. The "eprint" Set is the collection of all the eprints (or "publications") of your repository. It is the assumed Set when no set is declared, as for the scenario "show me the top publications [among the entire repository]".

==Reports==
Reports are single pages which group different metrics together. The main report page (http://yourrepo.url/cgi/stats/report) is such an example. If you create a new report, "my_report", it will be available at the URL: http://yourepo.url/cgi/stats/report/my_report.

In the configuration, Reports can be seen as a top-to-bottom stack of Stats::View modules. Such modules know how to draw certain stats such as graphs, tables or pie charts, they just need to be position on the report. The module handling the generation of reports (Screen::IRStats2::Report) takes care of passing on the correct context to each Stats::View module. Such contexts include any date filters or set values selected by a visiting user.

<pre>
#A basic report showing the monthly downloads graph and the top downloaded publications:
my_report => {
items => [
{
plugin => 'ReportHeader'
},
{
plugin => 'Google::Graph',
datatype => 'downloads',
options => {
date_resolution => 'month',
graph_type => 'column',
},
},
{
plugin => 'Table',
datatype => 'downloads',
options => {
limit => 10,
top => 'eprint',
title_phrase => 'top_downloads'
},
},

],
};
</pre>

The '''options''' are detailed in the [https://wiki.eprints.org/w/IRStats2#API API] section.

==Security==
Users must have the following two roles to view stats:

*+irstats2/view
*+irstats2/export

However these two roles are given to the "public" by default, meaning that anyone can view and/or export the stats. These lines may be commented out in the configuration to prevent this behaviour.

=API=

This section presents a few examples on how to get data out of IRStats2 for embedding data on pages or for re-use in analysis scripts (for instance).

There are two ways to get data out:

#From a script: this is the real API, using PERL
#From an Ajax request: this is usually to embed data on pages

==Core concepts==

===Datatype===
Datatype refers to which data to provide with IRStats2 able to process any of data on your repository. The typical use of IRStats2 is however for usage statistics so this is the main dataset, but data on deposits, open access, full text (etc) are also processed. Some repositories even include data from Scopus (citation counts).

Main datatypes:

*downloads: good old download statistics - downloads of full-text documents
*views: number of hits on the summary page (of a publication)
*deposits: number of publications deposited
*doc_access: provides 4 metrics (full_text, no_full_text, open_access and no_open_access) used for computing percentages of Open Access and Full-Text *documents in the repository
*doc_format: MIME type of full-texts
*history: analysis of the "history" dataset - this provides information on when publications were created, edited, made live, deleted etc.
*referrer: information on how site visitors got to the repository (e.g. from Google, internal uni pages, etc)
*search_terms: if coming from a search site (or the internal EPrints search) which words were used to get to the publication
*browser: which browser visitors used on the repository

===Sets===
By default, IRStats2 returns data over the entire repository, i.e. the entire set of eprints is assumed. You can however restrict which "set" to use: the publications of an author, of a university division, of a subject, etc.

===Dates and ranges===
You can also restrict by dates or by a range. By default, all the stats are returned without any dates restrictions.

Dates can be set as YYYYMMDD or YYYY-MM-DD or YYYY/MM/DD (e.g. 20170101, 2017-11-04 etc). Dates is a hash containing two keys: from and to (either may be omitted to say: from that particular date, or up to that particular date).

Ranges follow a %d%c format and the upper limit is "now" or "today", for instance:

*6m: over the past 6 months
*12d: over the past 12 days
*3y: over the past 3 years

Only "m" (months), "d" (days) or "y" (years) may be used. 12m is the same as 1y.

===Groupings===
This tells IRStats2 how to group data and is generally only used for things like "give me the TOP eprints", "give me the TOP authors".

So having a "grouping" set to "eprint" means the top eprints. If set to "authors", the top authors etc. The grouping must be a valid set except for when it equals to "eprint".

===Misc===
It is possible to limit the amount of records being returned (for when this is relevant: if you want the top downloads, since the beginning of time, then you'd only get one data row back, which is that count). But for queries which ask for, say, the top authors, it is then interesting to be able to get only the first 10 authors. 10 here is the limit.

It is also possible to ask IRStats2 to return certain data field in queries. For top eprints, you generally want the "eprintid" field. To draw timeline graphs (eg. evolution of downloads over-time), you'd want the "datestamp" field. More examples are illustrated below.

==Data from scripts==

===Main API===

<pre>
# get the IRStats2 handler, required to query IRStats2
my $handler = $repo->plugin( "Stats::Handler" );

# ask IRStats2 to show debug statements (SQL queries)
$handler->debug(1);

# Create a Context object
my $ctx = $handler->context( { datatype: "downloads" } );

# Retrieve data rows
my $data = $handler->data( $ctx )->select();

# How many rows returned:
printf "I got %d data rows back\n", $data->count;

# Get stats for divisions "uos-ecs":
$ctx->set( { set_name => 'divisions', set_value => 'uos-ecs' } );

# Get stats over the last 6 months:
$ctx->dates( { range => '6m' } );

# Get stats between 1st January 2012 and 31st March 2012:
$ctx->dates( { from => '20120101', to => '20120331' } );

# Data may be exported (see Stats/Export/ for a list of currently supported plug-ins):
my $export = $repo->plugin( "Stats::Export::CSV" );
$data->export( { export_plugin => $export } );
</pre>

===Full Examples===
Actually those are not really full examples. They assume you can write the beginning of a PERL script and that you have already instantiated the Stats Handler (cf. above) as $handler.

<pre>
# How many downloads in total over the entire repository
my $ctx = $handler->context( { datatype => "downloads" } );
printf "I got %d downloads\n", $handler->data( $ctx )->select->sum_all;
</pre>

<pre>
# How many downloads in 2013 over the entire repository
my $ctx = $handler->context( { datatype => "downloads", range => "2013" } );
printf "I got %d downloads\n", $handler->data( $ctx )->select->sum_all;
</pre>

<pre>
# The top 5 EPrints over the entire repository
my $ctx = $handler->context( { grouping => "eprint", datatype => "downloads" } );

my $stats = $handler->data( $ctx )->select( fields => ["eprintid"], limit => 5 );

foreach( @{ $stats->data } )
{
printf "EPrint %d got %d downloads\n", $_->{eprintid}, $_->{count};
}
</pre>

<pre>
# The top 10 Subjects (let's assume LoC) for deposits (not downloads!!)
my $ctx = $handler->context( { set_name => "subjects", datatype => "deposits" } );

my $stats = $handler->data( $ctx )->select( fields => ["set_value"], limit => 10 );

my $i = 1;
foreach( @{ $stats->data } )
{
printf "%d) %s with %d items deposited\n", $i++, $_->{set_value}, $_->{count};
}
</pre>

<pre>
# The top 5 downloaded EPrints for LoC Subject "D1"
my $ctx = $handler->context( { set_name => "subjects", set_value => 'D1', datatype => "downloads" } );

my $stats = $handler->data( $ctx )->select( fields => ["eprintid"], limit => 5 );

my $i = 1;
foreach( @{ $stats->data } )
{
printf "%d) EPrintd %d with %d downloads\n", $i++, $_->{eprintid}, $_->{count};
}
</pre>

==Embedding data==
This is similar to retrieving data from scripts (cf. section above) but with a few extra options:

*"view": the name of the Stats::View plug-in which will draw the requested stuff (a Table? a Graph? etc.)
*"container_id": the DOM element "id", where the drawn stuff will be inserted on the page (if the Ajax callback is successful)

Then there exists a number of options proper to each View plug-in. See the provided examples below.

===Graphs===
The typical example is to embed the global downloads graph. This is usually the first displayed item on the IRStats2 main report page (/cgi/stats/report).

<pre>


<div id="mygraph" class="irstats2_googlegraph"/>

<script type="text/javascript">
document.observe("dom:loaded",function(){
new EPJS_Stats_GoogleGraph( {
'context': {'irs2report': 'main', 'range': '_ALL_', 'datatype': 'downloads'},
'options': { 'graph_type': 'column', 'container_id': 'mygraph', 'view': 'Google::Graph', 'show_average': '1', 'date_resolution': 'month' }
});
});
</script>
</pre>

===Tables===
The example below displays the top 10 downloaded eprints in the repository.

<pre>

<div id="mytable" class="irstats_table"/>

<script type="text/javascript">
document.observe( "dom:loaded", function() {

new EPJS_Stats_Table( {
'context': { 'irs2report': 'most_popular_eprints', 'range': '_ALL_', 'datatype': 'downloads'},
'options': { 'container_id': 'mytable', 'top': 'eprint', 'view': 'Table', 'limit': '5' }
} );

});
</script>
</pre>

===Misc===
Graphs and Tables are the most common displays, but there are a few other ones to explore. The javascript classes are in 90_irstats2.js and the associated PERL Class in Stats/View/

*GoogleSpark: similar to GoogleGraph but shows a sparkline instead (which is essentially a tiny graph).
*GoogleGeoChart: country map
*GooglePieChart: a pie chart
*Counter: a simple counter (for instance to show the download count for your repository).

The View prefixed by "Google" means that they are rendered by the Google Chart Javascript library. Important note: no data is sent to Google! The data is, instead, drawn by the browser client using SVG.

== Example: Creating a processor for citation statistics ==

IRStats2 can evaluate any field or combination of fields in the above mentioned datasets. For this, new datatypes and associated Stats::Processor modules must be created.

A simple case is statistics on citation count of publications, since the datatype of the associated field is a scalar.

Citation counts can be harvested using the [http://files.eprints.org/815/ Citation count dataset and import plugins] from Queensland University of Technology. Upon following the installation procedure, the fields scopus_impact, wos_impact and gscholar_impact are created in the EPrint table.

=== Modifying an existing Processor module ===

We create now a Processor module that evaluates the scopus_impact field and provides a scopus_citations datatype.

First, we inspect the Stats::Processor::EPrint Processor modules to find out which Processor module is best suited for adapting. A good candidate is lib/plugins/EPrints/Plugin/Stats/Processor/EPrint/DocumentAccess.pm. We copy it to archives/{repo}/cfg/plugins/EPrints/Plugin/Stats/Process/EPrint/ScopusCitations.pm and modify it as follows:

<pre>
package EPrints::Plugin::Stats::Processor::EPrint::ScopusCitations;

our @ISA = qw/ EPrints::Plugin::Stats::Processor /;

use strict;

sub new
{
my( $class, %params ) = @_;
my $self = $class->SUPER::new( %params );

# provide the name of the datatype
$self->{provides} = [ "scopus_citations" ];

$self->{disable} = 0;

return $self;
}

sub process_record
{
my ($self, $eprint ) = @_;

my $epid = $eprint->get_id;
return unless( defined $epid );

my $status = $eprint->get_value( "eprint_status" );
unless( defined $status )
{
## print STDERR "IRStats2: warning - status not set for eprint=".$eprint->get_id."\n";
return;
}

return unless( $status eq 'archive' );

my $datestamp = $eprint->get_value( "datestamp" ) || $eprint->get_value( "lastmod" );

my $date = $self->parse_datestamp( $self->{session}, $datestamp );

my $year = $date->{year};
my $month = $date->{month};
my $day = $date->{day};

# get the citation count
my $scopus_citation_count = $eprint->get_value( "scopus_impact" );

# store the citation count per eprint id
if (defined $scopus_citation_count)
{
$self->{cache}->{"$year$month$day"}->{$epid}->{scopus} = $scopus_citation_count;
}
}

1;
</pre>

Next, we need to enable the new Processor plugin in our IRStats2 configuration file. In the Bazaar config section, add the following line:

<pre>
$c->{plugins}{"Stats::Processor::EPrint::ScopusCitations"}{params}{disable} = 0;
</pre>

In the Reports section, we can add now a new citation report that uses the scopus_citations datatype:

<pre>
citations => {
items => [
{ plugin => 'ReportHeader' },
{
plugin => 'Grid',
options => {
items => [
{
plugin => 'Table',
datatype => 'scopus_citations',
options => {
limit => 10,
top => 'eprint',
title_phrase => 'top_scopus_citations',
},
},]
},
},
{
plugin => 'Grid',
options => {
items => [
{
plugin => 'Table',
datatype => 'scopus_citations',
options => {
limit => 10,
top => 'authors',
title_phrase => 'top_scopus_citations_authors'
}
},]
},
},
],
category => 'advanced',
},
</pre>

Also, the phrases in irstats2.xml must be completed accordingly.

=== Generalization ===

For each citation datum, a processor module is required. We see, that these will differ only slightly,
namely in the datatype declaration in the new() method, and in the processing of the citation datum field
in the last part of the process_record() method. Therefore, we can generalize the processor by providing
an abstract value tracker module. It does the following:

In the new() method, it provides an abstract value tracker datatype. Note that the plugin is disabled.
In the process_record() method, it makes reference to the field that is processed and a value_id to where the value will be stored.

<pre>
package EPrints::Plugin::Stats::Processor::EPrint::AbstractValueTracker;

our @ISA = qw/ EPrints::Plugin::Stats::Processor /;

use strict;

sub new
{
my( $class, %params ) = @_;
my $self = $class->SUPER::new( %params );

$self->{provides} = [ "abstract_value_tracker" ];
$self->{disable} = 1;

$self->{field_id} = 'DEFINE IN SUBCLASS';
$self->{value_id} = 'DEFINE IN SUBCLASS';

return $self;
}

sub process_record
{
my ($self, $eprint ) = @_;

my $epid = $eprint->get_id;
return unless( defined $epid );

my $status = $eprint->get_value( "eprint_status" );
unless( defined $status )
{
# print STDERR "IRStats2: warning - status not set for eprint=".$eprint->get_id."\n";
return;
}

return unless( $status eq 'archive' );

my $datestamp = $eprint->get_value( "datestamp" ) || $eprint->get_value( "lastmod" );

my $date = $self->parse_datestamp( $self->{session}, $datestamp );

my $year = $date->{year};
my $month = $date->{month};
my $day = $date->{day};

my $value = $eprint->value($self->{field_id});

if (defined $value)
{
$self->{cache}->{"$year$month$day"}->{$epid}->{$self->{value_id}} = $value;
}
}

1;
</pre>

Now, the declaration of new scalar datatypes reduces to the task to defining a subclass for each datatype,
and to declaring the assocation between the datatype and the field to be processed in the IRStats2 configuration:

<pre>
package EPrints::Plugin::Stats::Processor::EPrint::ScopusCitations;

use EPrints::Plugin::Stats::Processor::EPrint::AbstractValueTracker;
our @ISA = qw/ EPrints::Plugin::Stats::Processor::EPrint::AbstractValueTracker /;

use strict;

sub new
{
my( $class, %params ) = @_;
my $self = $class->SUPER::new( %params );
my $repo = $self->repository;

$self->{provides} = [ "scopus_citations" ];

$self->{disable} = 0;

$self->{field_id} = $repo->config('irstats2','scopus_citations','field_id');
$self->{value_id} = 'scopus';

return $self;
}

1;
</pre>

<pre>
############
# Datatypes
############
# Declare as $c->{irstats2}->{datatypename}->{field_id} = 'fieldname';

$c->{irstats2}->{scopus_citations}->{field_id} = 'scopus_impact';
</pre>

=== Specific requirements by Scopus and Web of Science ===

If you have a valid API key to the Scopus and Web of Science APIs, it is allowed by both database producers to show aggregate citation counts, given that a link back to the record in the Scopus and Web of Science database and attribution to their brand is provided. I leave that to you to figure out how this can be achieved in the Table view.

Google Scholar does not allow to harvest citation counts.

=Troubleshooting=
=== No style on stats ===

If you attempt to view the stats panel and it does not render correctly, run generate_static and restart apache.

=== Can't call method "add_trigger" ===

Error when running process_stats:

<pre>
Use of uninitialized value in concatenation (.) or string at (eval 70) line 11.
Use of uninitialized value in concatenation (.) or string at (eval 70) line 16.
Use of uninitialized value in concatenation (.) or string at (eval 70) line 19.

------------------------------------------------------------------
---------------- EPrints System Error ----------------------------
------------------------------------------------------------------
Error in configuration:
Can't call method "add_trigger" on unblessed reference at /usr/share/eprints3/archives/sandbox/bin/../cfg/cfg.d/z_irstats2.pl line 162.

------------------------------------------------------------------
EPrints System Error inducing stack dump
at /usr/share/eprints3/archives/sandbox/bin/stats/../../../../perl_lib/EPrints.pm line 146.
EPrints::abort("EPrints") called at /usr/share/eprints3/archives/sandbox/bin/stats/../../../../perl_lib/EPrints/Config.pm line 151
EPrints::Config::load_system_config() called at /usr/share/eprints3/archives/sandbox/bin/stats/../../../../perl_lib/EPrints/Config.pm line 96
EPrints::Config::init() called at /usr/share/eprints3/archives/sandbox/bin/stats/../../../../perl_lib/EPrints.pm line 706
require EPrints.pm called at /usr/share/eprints3/archives/sandbox/bin/stats/process_stats line 12
main::BEGIN() called at /usr/share/eprints3/archives/sandbox/bin/stats/../../../../perl_lib/EPrints.pm line 0
eval {...} called at /usr/share/eprints3/archives/sandbox/bin/stats/../../../../perl_lib/EPrints.pm line 0
</pre>

This is due to the FindBin library not working correctly. Open the process_stats script and remove the line:

<pre>
use lib "$FindBin::Bin/../../../../perl_lib";
</pre>

When executing, use -I to explicitly set the EPrints perl_lib directory:

<pre>
perl -I/EPRINTS_ROOT/perl_lib /EPRINTS_ROOT/archives/ARCHIVEID/bin/stats/process_stats
</pre>

=== Argument "/opt/eprints3/lib/geoip/GeoIP.dat" isn't numeric ===

If you see the error:

<pre>
Argument "/opt/eprints3/lib/geoip/GeoIP.dat" isn't numeric in subroutine entry at /opt/eprints3/lib/plugins/EPrints/Plugin/Stats/Processor/Access/Country.pm line 36, <DATA> line 960.
</pre>

This is due to a change in functionality of the GeoIP library. Open the file:

/EPRINTS_ROOT/lib/plugins/EPrints/Plugin/Stats/Processor/Access/Country.pm

... and replace the line:

$self->{geoip} = $pkg->new( $dat_file );

... with ...

$self->{geoip} = $pkg->open( $dat_file );

Remember to add a suitable comment identifying who made the change, when it was made and why. This will make upgrading easier.

=== process_stats locked ===

If IRStats terminates prematurely, it can leave a lock in the database that will need to be removed. A script has been written to release this lock, but should only be run if you are certain that IRStats2 is not currently running. The code is available on [https://github.com/gobfrey/irstats2_clear_lock github].

User Deposit Agreement

2023-12-04T15:48:27Z

Ejo1f20:

== DOCUMENTATION NOT COMPLETE ==

== Why add a user deposit agreement? ==

You may wish for users to explicitly comply with a set of user agreement terms and conditions. The terms may be stated in a hosted file which can be linked to or hosted within your eprints instance as a pdf or xpage file.

== Versions ==

EPrints 3.4 (All minor versions)

== Process for adding a user deposit agreement ==

To be written...

User Deposit Agreement

2023-12-04T15:47:18Z

Ejo1f20: Created page with "== DOCUMENTATION NOT COMPLETE == == Why add a user deposit agreement? == You may wish for users to explicitly comply with a set of user agreement terms and conditions. The t..."

== DOCUMENTATION NOT COMPLETE ==

== Why add a user deposit agreement? ==

You may wish for users to explicitly comply with a set of user agreement terms and conditions. The terms may be stated in a hosted file which can be linked to or hosted within your eprints instance as a pdf or xpage file.

== Process for adding a user deposit agreement ==

To be written...

Manual

2023-12-04T15:44:11Z

Ejo1f20: /* How-to Guides */

__NOTOC__
See the [[Main Page]] for other areas of this wiki.

* [[Introduction|Introduction to EPrints]] and [[History|History of EPrints]]

<table cellpadding="10"><tr><td width="33%" valign="top">
= Releases =
{{releasenotes}}
''See also the note on [[EPrints Version Numbering]]''

= Download =
{{Download}}

= Installation =
* [[Recommended Platforms]]
* [[Required software]]
* Install Guides
** [[Installing EPrints on RHEL/Fedora/CentOS]]
*** Primarily RedHat Enterprise Linux (RHEL) and CentOS 7 and 8.
*** Guides for installing from RPM package and from source.
** [[Installing EPrints on Debian/Ubuntu]]
*** Primarily Ubuntu 18.04 LTS and 20.04 LTS.
*** Guides for installing from Deb package and from source.
* [[Installation|Generic EPrints installation instructions]]
* [[How to use EPrints with HTTPS]]
** [[Setting up HTTPS using Let's Encrypt]]
** [[HTTPS-only and HSTS]]
* [[Installing EPrints using Docker]]

= Post Installation =
* [[Getting Started with EPrints 3]]

= Maintenance =
* [[Backups]]
* [[Generate Scripts]]
* [[Alerts]]
* [[Log Files]]
* [[Automating your maintenance]]
* [[Troubleshooting]]
</td>

<td width="33%" valign="top" style="border-left: solid 1px #ccc; border-right: solid 1px #ccc;">

= Training Materials =
* [[:Category:Training Video|EPrints Training Course]]
* [http://www.eprints.org/software/training/ Training materials] provided by EPrints Services.

= How-to Guides =
''[http://en.wikipedia.org/wiki/Howto What is a how-to?]

* [[:Category:Howto|Orientation/Overview]] <span style="color: #f94; font-size: 130%">(Start here)</span>
** [[Configuration orientation|New to EPrints 3?]] - ''before diving into the how-tos, take some time to read through this brief orientation guide and familiarise yourself with the EPrints configuration landscape ...''
* [[Front Page Warning | Removing the Front Page Warning]] - Your first go at branding
* [[Branding with confidence]] - ''one of the most common EPrints customisations is to add your own institution's branding and "look and feel" to the interface...''
** [[Branding, the next level]] - ''how to completely change the interface to your own design''
* [[OAI]]
* [[Adding new views]]
* Workflow
* Deposit Types
** [[Removing types]]
* Metadata
* Subjects (fold in with Organisation Hierarchy under "controled vocabularies")
* [[EPrints_3_Organisation_Hierarchy|Organisation Hierarchy]] - ''how to put your own organisation's Hierarchy into EPrints 3''
* Searches
* [[Autocompletion and Authority Files (Romeo Autocomplete)]] - ''add autocomplete functionality to the Publication Title input field based on an authority file downloaded from EPrints Romeo...''
* [[Create Export Plugins]] - ''create a Perl Module that will export your data...''
* [[Login-Only Repository]] - ''require a username and password to access all pages (including search, browse, and the front page)...''
* [[Change Deposit Status in Bulk]] - ''move a large number of deposits from inbox to archive.''
* [[SWORD]] - ''how to configure the SWORD protocol on EPrints.''
* [[Custom handlers]] - ''how to add a custom handler for intergration with third-party applications.''
* [[User Deposit Agreement]] - ''How to add a user deposit agreement to the workflow.''

= How to contribute =
There's a number of different ways you can contribute to the EPrints project. This section covers all the ones we can think of...

Always make an entry on http://files.eprints.org/ for your contribution, even if you don't upload the files. This will make it the one-stop place for people to find EPrints extensions.

* [[:Category:Documentation Needed| Create some of the missing documentation]]
* [[Contribute: Plugins | Plugins]]
* [[Contribute: Scripts | Scripts]]
* [[Contribute: Themes | Themes]]
* [[Contribute: Translations | Translations]]
* [[Contribute: Other | Other neighbourly things to do]]
* [[Extension Packages]]

= Misc =
* [[Preservation Support]] in EPrints 3
* [[:Category:Languages|Language support and translations]]
</td><td valign="top" width="33%">

= Technical Reference =
* [[EPrints Directory Structure]] - How code and configuation files are organised.
* [[EPrints Glossary]] - A listing of terminology used within EPrints.
* [[User Menu]] - Explaining the menu options available to an EPrints user.
* [[Admin|Admin Menu]] - Explaining the tools available to a repository administrator.
* [[Metadata]] - configuring metadata fields.
* [[Archives/ARCHIVEID/cfg/|Repository Configuration]]
* [[XML Configuration]] Files
** [[EPScript]] - documentation for the EP3 Scripting language (for use in citations and workflow files).
** [[EPrints Control Format]] - the structure used to embed EPScript in an XML configuration file.
** [[Citation Format]]
** [[Workflow Format]] - the structure of the EP3 workflow files
** [[Phrase Format]]
** [[Template Format]]
** [[XPAGE Format]]
* [[XML Export Format]]
* EPrints data structure
** of the software
** of the database (relating the dataobjects to each other using eprints fields)
* [[Data Object]]s and data sets
** The [[EPrint Object]]
** The [[User Object]]
** The [[Document Object]]
** The [[Subject Object]]
** The [[Saved Search Object]]
** The [[History Object]]
** The [[Access Object]]
** The [[Request Object]]
* [[:Category:Plugins|Plugins]]
** [[Create Export Plugins|Export]]
** Import
** [[Screen Plugins|Screen]]
* [[Autocompletion]]
** [[Understanding IDs in Workflow Forms]]
* [[API]]
* [[Dynamic Template System]]

= The EPrints Bazaar =
* [[:Category:EPrints_Bazaar|The EPrints Bazaar]] (Start Here)
* The [[EPM Specification]]
* [[:Category:Bazaar_Package|Bazaar Packages]]

</td></tr></table>

ReCollect

2023-12-01T12:44:37Z

Ejo1f20:

[[Category:Bazaar_Package]]
[[Category:Documentation_Needed]]
[[Category:EPrints_3_Plugins]]

{{Deprecated|This plugin is not supported. The recollect plugin is 10+ years old and has not been updated to work with modern versions of EPrints (3.4+). Installing this is not recommended.}}

ReCollect is a Bazaar package for EPrints which transforms an EPrints install into a research data repository. Fields are compliant with the DataCite and INSPIRE metadata schema. This plugin was created by the UK Data Archive led Research Data @Essex project (http://www.data-archive.ac.uk/create-manage/projects/rd-essex). Thanks to the DataPool project at the University of Southampton (http://datapool.soton.ac.uk/) for their assistance in packaging the plugin.

ReCollect lowers the barrier for deploying a full-featured and standards compliant research data repository. The only prerequisite is a clean EPrints install. From there, a user with an administrative account can use the EPrints Bazaar option in the System Tools menu to install ReCollect with just one click.

== Features ==

ReCollect features are too numerous to document here in their entirety, but can be summarised as follows:

* Redesigned Abstract page to present complex data collections, consisting of many files of different types.

* Expanded metadata profile to describe research data, built on the DataCite, INSPIRE and Data Documentation Initiative (2.1) metadata schemas. The metadata profile used has been published by the UK Data Archive (http://www.data-archive.ac.uk/media/375386/rde_eprints_metadataprofile.pdf).

* Many tweaks to workflow and validations.

* Revised and expanded field labels and help phrases.

'''Can I install ReCollect on a pre-populated repository?'''

It is possible to integrate ReCollect with an existing repository; however this would require edits to the code in order to switch back on features that ReCollect hides, namely the Eprint Type selection as the first stage of deposit (e.g. Article, Book, Dataset etc). This is not how ReCollect was tended to be used, so we would only recommend you do this if you are confident working with the EPrints code base.

== Further information ==

The following outputs of the Research Data @Essex project may be of interest to users of ReCollect:

* Research data repository policies devised for the University of Essex pilot (http://www.data-archive.ac.uk/media/391126/rdessex_recollectpolicies.pdf)

* User documentation created for the University of Essex pilot, aimed at helping research prepare and deposit data (http://www.data-archive.ac.uk/media/391123/rdessex_recollectuserguide.pdf)

* The metadata profile (http://www.data-archive.ac.uk/media/375386/rde_eprints_metadataprofile.pdf) used by ReCollect and the mapping on which it is based (http://www.data-archive.ac.uk/media/375383/rde_eprints_metadatamapping.pdf)

A full report on the development of the ReCollect plugin and the rationale behind it will be published shortly, and a link added here.

'''Contact'''

Please contact Alexis Wolton with any queries regarding use of the plugin: [mailto:awolton@essex.ac.uk awolton@essex.ac.uk]