C4/Auth_with_shibboleth.pm

   1 package C4::Auth_with_shibboleth;
   2
   3 # Copyright 2011 BibLibre
   4 #
   5 # This file is part of Koha.
   6 #
   7 # Koha is free software; you can redistribute it and/or modify it under the
   8 # terms of the GNU General Public License as published by the Free Software
   9 # Foundation; either version 2 of the License, or (at your option) any later
  10 # version.
  11 #
  12 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
  13 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  14 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License along
  17 # with Koha; if not, write to the Free Software Foundation, Inc.,
  18 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  19
  20 use strict;
  21 use warnings;
  22
  23 use C4::Debug;
  24 use C4::Context;
  25 use Carp;
  26 use CGI;
  27
  28 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $debug);
  29
  30 BEGIN {
  31     require Exporter;
  32     $VERSION = 3.03;                                                                    # set the version for version checking
  33     $debug   = $ENV{DEBUG};
  34     @ISA     = qw(Exporter);
  35     @EXPORT  = qw(logout_shib login_shib_url checkpw_shib get_login_shib);
  36 }
  37 my $context = C4::Context->new() or die 'C4::Context->new failed';
  38 my $shib = C4::Context->config('shibboleth') or croak 'No <shibboleth> in koha-conf.xml';
  39 my $shibbolethMatchField     = $shib->{matchpoint} or croak 'No <matchpoint> defined in koha-conf.xml';
  40 my $shibbolethMatchAttribute = $shib->{mapping}->{$shibbolethMatchField}->{is} or croak 'Matchpoint not mapped in koha-conf.xml';
  41 my $protocol = "https://";
  42
  43 # Logout from Shibboleth
  44 sub logout_shib {
  45     my ($query) = @_;
  46     my $uri = $protocol . C4::Context->preference('OPACBaseURL');
  47     print $query->redirect( $uri . "/Shibboleth.sso/Logout?return=$uri" );
  48 }
  49
  50 # Returns Shibboleth login URL with callback to the requesting URL
  51 sub login_shib_url {
  52
  53     my ($query) = @_;
  54     my $param = $protocol . C4::Context->preference('OPACBaseURL') . $query->script_name();
  55     if ( $query->query_string() ) {
  56         $param = $param . '%3F' . $query->query_string();
  57     }
  58     my $uri = $protocol . C4::Context->preference('OPACBaseURL') . "/Shibboleth.sso/Login?target=$param";
  59     return $uri;
  60 }
  61
  62 # Returns shibboleth user login
  63 sub get_login_shib {
  64
  65     # In case of a Shibboleth authentication, we expect a shibboleth user attribute
  66     # to contain the login match point of the shibboleth-authenticated user. This match
  67     # point is configured in koha-conf.xml
  68
  69     # Shibboleth attributes are mapped into http environmement variables, so we're getting
  70     # the match point of the user this way
  71
  72     $debug and warn "koha borrower field to match: $shibbolethMatchField";
  73     $debug and warn "shibboleth attribute to match: $shibbolethMatchAttribute";
  74     $debug and warn "$shibbolethMatchAttribute value: $ENV{$shibbolethMatchAttribute}";
  75
  76     return $ENV{$shibbolethMatchAttribute} || '';
  77 }
  78
  79 # Checks for password correctness
  80 # In our case : does the given attribute match one of our users ?
  81 sub checkpw_shib {
  82     $debug and warn "checkpw_shib";
  83
  84     my ( $dbh, $userid ) = @_;
  85     my $retnumber;
  86     $debug and warn "User Shibboleth-authenticated as: $userid";
  87
  88     # Does the given shibboleth attribute value ($userid) match a valid koha user ?
  89     my $sth = $dbh->prepare("select cardnumber, userid from borrowers where $shibbolethMatchField=?");
  90     $sth->execute($userid);
  91     if ( $sth->rows ) {
  92         my @retvals = $sth->fetchrow;
  93         $retnumber = $retvals[1];
  94         $userid = $retvals[0];
  95         return ( 1, $retnumber, $userid );
  96     }
  97
  98     # If we reach this point, the user is not a valid koha user
  99     $debug and warn "User $userid is not a valid Koha user";
 100     return 0;
 101 }
 102
 103 1;
 104 __END__
 105
 106 =head1 NAME
 107
 108 C4::Auth_with_shibboleth
 109
 110 =head1 SYNOPSIS
 111
 112 use C4::Auth_with_shibboleth;
 113
 114 =head1 DESCRIPTION
 115
 116 This module is specific to Shibboleth authentication in koha and relies heavily upon the native shibboleth service provider package in your operating system.
 117
 118 =head1 CONFIGURATION
 119
 120 To use this type of authentication these additional packages are required:
 121
 122 =over
 123
 124 =item *
 125
 126 libapache2-mod-shib2
 127
 128 =item *
 129
 130 libshibsp5:amd64
 131
 132 =item *
 133
 134 shibboleth-sp2-schemas
 135
 136 =back
 137
 138 We let the native shibboleth service provider packages handle all the complexities of shibboleth negotiation for us, and configuring this is beyond the scope of this documentation.
 139
 140 But to sum up, to get shibboleth working in koha, as a minimum you will need to:
 141
 142 =over
 143
 144 =item 1.
 145
 146 Create some metadata for your koha instance (if you're in a single instance setup then the default metadata available at https://youraddress.com/Shibboleth.sso/Metadata should be adequate)
 147
 148 =item 2.
 149
 150 Swap metadata with your Identidy Provider (IdP)
 151
 152 =item 3.
 153
 154 Map their attributes to what you want to see in koha
 155
 156 =item 4.
 157
 158 Tell apache that we wish to allow koha to authenticate via shibboleth.
 159
 160 This is as simple as adding the below to your virtualhost config:
 161
 162  <Location />
 163    AuthType shibboleth
 164    Require shibboleth
 165  </Location>
 166
 167 =item 5.
 168
 169 Configure koha to listen for shibboleth environment variables.
 170
 171 This is as simple as enabling B<useshibboleth> in koha-conf.xml:
 172
 173  <useshibboleth>1</useshibboleth>
 174
 175 =item 6.
 176
 177 Map shibboleth attributes to koha fields, and configure authentication match point in koha-conf.xml.
 178
 179  <shibboleth>
 180    <matchpoint>userid<matchpoint> <!-- koha borrower field to match upon -->
 181    <mapping>
 182      <userid is="eduPersonID"></userid> <!-- koha borrower field to shibboleth attribute mapping -->
 183    </mapping>
 184  </shibboleth>
 185
 186 Note: The minimum you need here is a <matchpoint> block, containing a valid column name from the koha borrowers table, and a <mapping> block containing a relation between the chosen matchpoint and the shibboleth attribute name.
 187
 188 =back
 189
 190 It should be as simple as that; you should now be able to login via shibboleth in the opac.
 191
 192 If you need more help configuring your B<S>ervice B<P>rovider to authenticate against a chosen B<Id>entity B<P>rovider then it might be worth taking a look at the community wiki L<page|http://wiki.koha-community.org/wiki/Shibboleth_Configuration>
 193
 194 =head1 FUNCTIONS
 195
 196 =head2 logout_shib
 197
 198 Sends a logout signal to the native shibboleth service provider and then logs out of koha.  Depending upon the native service provider configuration and identity provider capabilities this may or may not perform a single sign out action.
 199
 200   logout_shib($query);
 201
 202 =head2 login_shib_url
 203
 204 Given a query, this will return a shibboleth login url with return code to page with given given query.
 205
 206   my $shibLoginURL = login_shib_url($query);
 207
 208 =head2 get_login_shib
 209
 210 Returns the shibboleth login attribute should it be found present in the http session
 211
 212   my $shib_login = get_login_shib();
 213
 214 =head2 checkpw_shib
 215
 216 Given a database handle and a shib_login attribute, this routine checks for a matching local user and if found returns true, their cardnumber and their userid.  If a match is not found, then this returns false.
 217
 218   my ( $retval, $retcard, $retuserid ) = C4::Auth_with_shibboleth::checkpw_shib( $dbh, $shib_login );
 219
 220 =head1 SEE ALSO
 221
 222 =cut