[Koha-devel] Fwd: Koha and Ebsco OpenAthens
Alex Buckley
alexbuckley at catalyst.net.nz
Tue Mar 24 22:10:21 CET 2020
Hi Paul,
I've done an integration of Openathens with Koha using the
mod_auth_mellon Apache module
https://github.com/latchset/mod_auth_mellon (rather than using the EBSCO
plugin).
The workflow I did is:
1. Checked out the master branch of mod_auth_mellon
2. Navigated into mod_auth_mellon
3. Generated the Koha SP (Service Provider) XML metadata endpoint, cert
and key file.
./mellon_create_metadata.sh <full_opac_test_site_url> <full_opac_test_site_url>/saml
4. Moved those files into a new directory /etc/koha/sites/<instance>/saml
5. Sent the metadata XML file I'd made to EBSCO and received their one
back and put it in /etc/koha/sites/<instance>/saml
6. Edit Apache conf file ( /etc/apache2/sites-available/<instance>.conf ):
<Location />
MellonEnable "auth"
MellonUser "NameID"
MellonSPPrivateKeyFile /etc/koha/sites/<instance>/saml/<opac_test_site_url>.key
MellonSPCertFile /etc/koha/sites/<instance>/saml/<opac_test_site_url>.cert
MellonSPMetadataFile /etc/koha/sites/<instance>/saml/<opac_test_site_url>.xml
MellonIdPMetadataFile /etc/koha/sites/<instance>/saml/<client_supplied_metadata>.xml
MellonEndpointPath /saml
# Set environment variables with the values of IdP attributes
MellonSetEnv "principalname" "<IdP_UPN_attribute_name>"
MellonSetEnv "givenname" "<IdP_firstaname_attribute_name>"
MellonSetEnv "surname" "<IdP_surname_attribute_name>"
MellonSetEnv "email" "<IdP_email_attribute_name>"
# Unset and reset X_REMOTE_UPN
Header unset X_REMOTE_UPN
RequestHeader unset X_REMOTE_UPN
RequestHeader set X_REMOTE_UPN %{MELLON_principalname}e
# Unset and reset the X_REMOTE_GIVENNAME
Header unset X_REMOTE_GIVENNAME
RequestHeader unset X_REMOTE_GIVENNAME
RequestHeader set X_REMOTE_GIVENNAME %{MELLON_givenname}e
# Unset and reset the X_REMOTE_SURNAME
Header unset X_REMOTE_SURNAME
RequestHeader unset X_REMOTE_SURNAME
RequestHeader set X_REMOTE_SURNAME %{MELLON_surname}e
# Unset and reset the X_REMOTE_EMAIL
Header unset X_REMOTE_EMAIL
RequestHeader unset X_REMOTE_EMAIL
RequestHeader set X_REMOTE_EMAIL %{MELLON_email}e
</location>
Here the /IdP_UPN_attribute_name/ is the attribute (claim) that
Openathens is sending to Koha in the SAML POST request, we're assigning
it to the Mellon environment variable "principalname" and then putting
it in the header as /X_REMOTE_UPN/
7. Install the following packages:
sudo apt-get install libapache2-mod-auth-mellon
sudo s2enmod expires
sudo systemctl restart apache2
sudo apachectl configtest
sudo apachectl restart
apt-cache policy libapache2-mod-auth-mellon
sudo apt-get install liblasso3
sudo apachectl restart
8. Amend the koha-conf.xml file adding the following tags:
<trusted_header_upn>X_REMOTE_UPN</trusted_header_upn>
<trusted_header_givenname>X_REMOTE_GIVENNAME</trusted_header_givenname>
<trusted_header_surname>X_REMOTE_SURNAME</trusted_header_surname>
<trusted_header_email>X_REMOTE_EMAIL</trusted_header_email>
9. Somethings to note is that using mod_auth_mellon is that plack user
runs as www-data so you will need to change the AssignUserID in the
Apache conf to be:
AssignUserID www-data <instance>-koha
You'll also need to amend your debian/scripts/koha-plack script to replace:
instance_user="${instancename}-koha"
With:
instance_user="www-data"
Also please note when using mod_auth_mellon you'll need to make sure the
Koha instance your setting this up for is on a standalone server (i.e.
no other Koha instance on the server) because the changing of the user
that Plack runs as introduces a security risk on a multi-instance server.
10. Change the ownership of /var/cache/koha/<instance> file, because
Plack now running as /www-data/ can not read the file:
sudo chown www-data -R /var/cache/koha/<instance>
11. You'll need to introduce a customization in C4/Auth.pm now (though I
am shortly going to be upstreaming this customization so you'll see a
bug report from me for it soon):
11a. Add a new subroutine get_header() - This retrieves the Openathens
values stored in the header in the Apache conf:
/sub get_header {/
//
/ my ($header) = @_;//
// my $q = CGI->new();//
// # Prepend HTTP_ as that's how they come through/
//
/ my $h_val = $q->http('HTTP_' . $header);//
// return $h_val;//
//}/
11b. Amend C4::Auth->checkauth():
/
/
/my $trusted_header = C4::Context->config('trusted_header');//
//my $trust_head_val = get_header($trusted_header) if $trusted_header;
#Store the header values returned from get_header subroutine which are:
UPN, givenname, surname and email in $trust_head_val hash. /
....
Now above this line (/elsif//( //$emailaddress//) {/ ) add in a new elsif:
/
/
/} elsif ($trust_head_val && $trust_head_val ne '(null)') {//
// $userid=$trust_head_val;//
// # This uses something like//
// # <trusted_header>X_REMOTE_USER</trusted_header>//
// # in koha-conf.xml, and checks that header on the incoming
request.//
// # If it is there and contains a user ID, we believe it and log
the//
// # user in with that. This is intended for things like plack
behind a//
// # reverse proxy that does auth, and puts the user ID into a
header.//
// #//
// # Basically, we treat it just like basic auth.//
// $cookie = $query->cookie(//
// -name => 'CGISESSID',//
// -value => '',//
// -expires => '',//
// -HttpOnly => 1,//
// );//
// C4::Context->_new_userenv(undef);//
// $loggedin = check_user_exists($userid); #Call
check_user_exists subroutine and check if there is a borrower.userid
matching the UPN//
// //
// }//
/
Note: This is assuming the UPN Openathens is sending Koha matches/is
stored in the borrower.userid. If Openathens wants to only use email
i.e. the email address Openathens sends Koha in POST request matches
borrowers.email then you'll need to amend the SQL query in
check_user_exists.
A couple more things to note:
1. If your Koha server is behind a load balancer then you need to
include the https:// directive in the servername e.g. Servername
https://demo.koha.com
This is because SAML requires the web server to identify as the same
server in the SP metadata (e.g. https://<URL>). But when a Koha server
is behind a LB it does not identify itself including the https protocol
so you need to include it.
There is more detail on that here:
https://jdennis.fedorapeople.org/doc/mellon-user-guide/mellon_user_guide.html#_server_name
I know that is for Fedora (I can't find the documentation link I had
discussing it in a Ubuntu context) but it is the same principal.
I hope all this helps and if you need any more information please let me
know!
Thanks,
Alex
On 25/03/20 5:00 am, Chris Cormack wrote:
>
>
> ------------------------------------------------------------------------
> *From:* Paul Poulain <paul.poulain at biblibre.com>
> *Sent:* 25 March 2020 4:57:14 AM NZDT
> *To:* "koha-devel at lists.koha-community.org"
> <koha-devel at lists.koha-community.org>
> *Subject:* [Koha-devel] Koha and Ebsco OpenAthens
>
> Hello,
>
> does anyone have experience in setting OpenAthens for Koha. There's an
> Ebsco plugin (https://github.com/ebsco/openathens-koha-plugin), but it
> seems to be for old versions of Koha.
>
> any feedback highly appreciated !
>
> --
> Paul Poulain, Associé-gérant / co-owner
> BibLibre, Services en logiciels libres pour les bibliothèques
> BibLibre, Open Source software and services for libraries
> ------------------------------------------------------------------------
> Koha-devel mailing list
> Koha-devel at lists.koha-community.org
> https://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
> website : http://www.koha-community.org/
> git : http://git.koha-community.org/
> bugs : http://bugs.koha-community.org/
>
> --
> Sent from my Android device with K-9 Mail. Please excuse my brevity.
--
Alex Buckley
Koha Developer
Catalyst IT - Expert Open Source Solutions
DDI: +64 4 803 2378 | Mob: +64 22 429 6157 | www.catalyst.net.nz
CONFIDENTIALITY NOTICE: This email is intended for the named recipients only. It may contain privileged, confidential or copyright information. If you are not the named recipient, any use, reliance upon, disclosure or copying of this email or its attachments is unauthorised. If you have received this email in error, please reply via email or call +64 4 499 2267.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.koha-community.org/pipermail/koha-devel/attachments/20200325/8a8632c3/attachment-0001.html>
More information about the Koha-devel
mailing list