C4/Auth_with_shibboleth.pm

   1 package C4::Auth_with_shibboleth;
   2
   3 # Copyright 2014 PTFS Europe
   4 #
   5 # This file is part of Koha.
   6 #
   7 # Koha is free software; you can redistribute it and/or modify it
   8 # under the terms of the GNU General Public License as published by
   9 # the Free Software Foundation; either version 3 of the License, or
  10 # (at your option) any later version.
  11 #
  12 # Koha is distributed in the hope that it will be useful, but
  13 # WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15 # GNU General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU General Public License
  18 # along with Koha; if not, see <http://www.gnu.org/licenses>.
  19
  20 use Modern::Perl;
  21
  22 use C4::Debug;
  23 use C4::Context;
  24 use Carp;
  25 use CGI;
  26
  27 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $debug);
  28
  29 BEGIN {
  30     require Exporter;
  31     $VERSION = 3.03;           # set the version for version checking
  32     $debug   = $ENV{DEBUG};
  33     @ISA     = qw(Exporter);
  34     @EXPORT =
  35       qw(shib_ok logout_shib login_shib_url checkpw_shib get_login_shib);
  36 }
  37
  38 # Check that shib config is not malformed
  39 sub shib_ok {
  40     my $config = _get_shib_config();
  41
  42     if ($config) {
  43         return 1;
  44     }
  45
  46     return 0;
  47 }
  48
  49 # Logout from Shibboleth
  50 sub logout_shib {
  51     my ($query) = @_;
  52     my $uri = _get_uri();
  53     print $query->redirect( $uri . "/Shibboleth.sso/Logout?return=$uri" );
  54 }
  55
  56 # Returns Shibboleth login URL with callback to the requesting URL
  57 sub login_shib_url {
  58     my ($query) = @_;
  59
  60     my $param = _get_uri() . $query->script_name();
  61     if ( $query->query_string() ) {
  62         $param = $param . '%3F' . $query->query_string();
  63     }
  64     my $uri = _get_uri() . "/Shibboleth.sso/Login?target=$param";
  65     return $uri;
  66 }
  67
  68 # Returns shibboleth user login
  69 sub get_login_shib {
  70
  71 # In case of a Shibboleth authentication, we expect a shibboleth user attribute
  72 # to contain the login match point of the shibboleth-authenticated user. This match
  73 # point is configured in koha-conf.xml
  74
  75 # Shibboleth attributes are mapped into http environmement variables, so we're getting
  76 # the match point of the user this way
  77
  78     # Get shibboleth config
  79     my $config = _get_shib_config();
  80
  81     my $matchAttribute = $config->{mapping}->{ $config->{matchpoint} }->{is};
  82     $debug and warn $matchAttribute . " value: " . $ENV{$matchAttribute};
  83
  84     return $ENV{$matchAttribute} || '';
  85 }
  86
  87 # Checks for password correctness
  88 # In our case : does the given attribute match one of our users ?
  89 sub checkpw_shib {
  90     $debug and warn "checkpw_shib";
  91
  92     my ( $dbh, $match ) = @_;
  93     my ( $retnumber, $userid );
  94     my $config = _get_shib_config();
  95     $debug and warn "User Shibboleth-authenticated as: $match";
  96
  97   # Does the given shibboleth attribute value ($match) match a valid koha user ?
  98     my $sth = $dbh->prepare(
  99         "select cardnumber, userid from borrowers where $config->{matchpoint}=?"
 100     );
 101     $sth->execute($match);
 102     if ( $sth->rows ) {
 103         my @retvals = $sth->fetchrow;
 104         $retnumber = $retvals[0];
 105         $userid    = $retvals[1];
 106         return ( 1, $retnumber, $userid );
 107     }
 108
 109     # If we reach this point, the user is not a valid koha user
 110     $debug
 111       and warn
 112       "User with $config->{matchpoint} of $match is not a valid Koha user";
 113     return 0;
 114 }
 115
 116 sub _get_uri {
 117
 118     my $protocol = "https://";
 119
 120     my $return = $protocol . C4::Context->preference('OPACBaseURL');
 121     return $return;
 122 }
 123
 124 sub _get_shib_config {
 125     my $config = C4::Context->config('shibboleth');
 126
 127     if ( !$config ) {
 128         carp 'shibboleth config not defined';
 129         return 0;
 130     }
 131
 132     if ( $config->{matchpoint}
 133         && defined( $config->{mapping}->{ $config->{matchpoint} }->{is} ) )
 134     {
 135         if ($debug) {
 136             warn "koha borrower field to match: " . $config->{matchpoint};
 137             warn "shibboleth attribute to match: "
 138               . $config->{mapping}->{ $config->{matchpoint} }->{is};
 139         }
 140         return $config;
 141     }
 142     else {
 143         if ( !$config->{matchpoint} ) {
 144             carp 'shibboleth matchpoint not defined';
 145         }
 146         else {
 147             carp 'shibboleth matchpoint not mapped';
 148         }
 149         return 0;
 150     }
 151 }
 152
 153 1;
 154 __END__
 155
 156 =head1 NAME
 157
 158 C4::Auth_with_shibboleth
 159
 160 =head1 SYNOPSIS
 161
 162 use C4::Auth_with_shibboleth;
 163
 164 =head1 DESCRIPTION
 165
 166 This module is specific to Shibboleth authentication in koha and relies heavily upon the native shibboleth service provider package in your operating system.
 167
 168 =head1 CONFIGURATION
 169
 170 To use this type of authentication these additional packages are required:
 171
 172 =over
 173
 174 =item *
 175
 176 libapache2-mod-shib2
 177
 178 =item *
 179
 180 libshibsp5:amd64
 181
 182 =item *
 183
 184 shibboleth-sp2-schemas
 185
 186 =back
 187
 188 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.
 189
 190 But to sum up, to get shibboleth working in koha, as a minimum you will need to:
 191
 192 =over
 193
 194 =item 1.
 195
 196 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)
 197
 198 =item 2.
 199
 200 Swap metadata with your Identidy Provider (IdP)
 201
 202 =item 3.
 203
 204 Map their attributes to what you want to see in koha
 205
 206 =item 4.
 207
 208 Tell apache that we wish to allow koha to authenticate via shibboleth.
 209
 210 This is as simple as adding the below to your virtualhost config:
 211
 212  <Location />
 213    AuthType shibboleth
 214    Require shibboleth
 215  </Location>
 216
 217 =item 5.
 218
 219 Configure koha to listen for shibboleth environment variables.
 220
 221 This is as simple as enabling B<useshibboleth> in koha-conf.xml:
 222
 223  <useshibboleth>1</useshibboleth>
 224
 225 =item 6.
 226
 227 Map shibboleth attributes to koha fields, and configure authentication match point in koha-conf.xml.
 228
 229  <shibboleth>
 230    <matchpoint>userid<matchpoint> <!-- koha borrower field to match upon -->
 231    <mapping>
 232      <userid is="eduPersonID"></userid> <!-- koha borrower field to shibboleth attribute mapping -->
 233    </mapping>
 234  </shibboleth>
 235
 236 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.
 237
 238 =back
 239
 240 It should be as simple as that; you should now be able to login via shibboleth in the opac.
 241
 242 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>
 243
 244 =head1 FUNCTIONS
 245
 246 =head2 logout_shib
 247
 248 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.
 249
 250   logout_shib($query);
 251
 252 =head2 login_shib_url
 253
 254 Given a query, this will return a shibboleth login url with return code to page with given given query.
 255
 256   my $shibLoginURL = login_shib_url($query);
 257
 258 =head2 get_login_shib
 259
 260 Returns the shibboleth login attribute should it be found present in the http session
 261
 262   my $shib_login = get_login_shib();
 263
 264 =head2 checkpw_shib
 265
 266 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.
 267
 268   my ( $retval, $retcard, $retuserid ) = C4::Auth_with_shibboleth::checkpw_shib( $dbh, $shib_login );
 269
 270 =head1 SEE ALSO
 271
 272 =cut