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 Koha::AuthUtils qw(get_script_name);
  25 use Koha::Database;
  26 use Koha::Patrons;
  27 use C4::Members::Messaging;
  28 use Carp;
  29 use CGI;
  30 use List::MoreUtils qw(any);
  31
  32 use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $debug);
  33
  34 BEGIN {
  35     require Exporter;
  36     $debug   = $ENV{DEBUG};
  37     @ISA     = qw(Exporter);
  38     @EXPORT =
  39       qw(shib_ok logout_shib login_shib_url checkpw_shib get_login_shib);
  40 }
  41
  42 # Check that shib config is not malformed
  43 sub shib_ok {
  44     my $config = _get_shib_config();
  45
  46     if ($config) {
  47         return 1;
  48     }
  49
  50     return 0;
  51 }
  52
  53 # Logout from Shibboleth
  54 sub logout_shib {
  55     my ($query) = @_;
  56     my $uri = _get_uri();
  57     print $query->redirect( $uri . "/Shibboleth.sso/Logout?return=$uri" );
  58 }
  59
  60 # Returns Shibboleth login URL with callback to the requesting URL
  61 sub login_shib_url {
  62     my ($query) = @_;
  63
  64     my $param = _get_uri() . get_script_name();
  65     if ( $query->query_string() ) {
  66         $param = $param . '%3F' . $query->query_string();
  67     }
  68     my $uri = _get_uri() . "/Shibboleth.sso/Login?target=$param";
  69     return $uri;
  70 }
  71
  72 # Returns shibboleth user login
  73 sub get_login_shib {
  74
  75 # In case of a Shibboleth authentication, we expect a shibboleth user attribute
  76 # to contain the login match point of the shibboleth-authenticated user. This match
  77 # point is configured in koha-conf.xml
  78
  79 # Shibboleth attributes are mapped into http environmement variables, so we're getting
  80 # the match point of the user this way
  81
  82     # Get shibboleth config
  83     my $config = _get_shib_config();
  84
  85     my $matchAttribute = $config->{mapping}->{ $config->{matchpoint} }->{is};
  86
  87     if ( any { /(^psgi\.|^plack\.)/i } keys %ENV ) {
  88       $debug and warn $matchAttribute . " value: " . $ENV{"HTTP_".uc($matchAttribute)};
  89       return $ENV{"HTTP_".uc($matchAttribute)} || '';
  90     } else {
  91       $debug and warn $matchAttribute . " value: " . $ENV{$matchAttribute};
  92       return $ENV{$matchAttribute} || '';
  93     }
  94 }
  95
  96 # Checks for password correctness
  97 # In our case : does the given attribute match one of our users ?
  98 sub checkpw_shib {
  99     $debug and warn "checkpw_shib";
 100
 101     my ( $match ) = @_;
 102     my $config = _get_shib_config();
 103     $debug and warn "User Shibboleth-authenticated as: $match";
 104
 105     # Does the given shibboleth attribute value ($match) match a valid koha user ?
 106     my $borrower =
 107       Koha::Database->new()->schema()->resultset('Borrower')
 108       ->find( { $config->{matchpoint} => $match } );
 109     if ( defined($borrower) ) {
 110         if ($config->{'sync'}) {
 111             _sync($borrower->borrowernumber, $config, $match);
 112         }
 113         return ( 1, $borrower->get_column('cardnumber'), $borrower->get_column('userid') );
 114     }
 115
 116     if ( $config->{'autocreate'} ) {
 117         return _autocreate( $config, $match );
 118     } else {
 119         # If we reach this point, the user is not a valid koha user
 120          $debug and warn "User with $config->{matchpoint} of $match is not a valid Koha user";
 121         return 0;
 122     }
 123 }
 124
 125 sub _autocreate {
 126     my ( $config, $match ) = @_;
 127
 128     my %borrower = ( $config->{matchpoint} => $match );
 129
 130     while ( my ( $key, $entry ) = each %{$config->{'mapping'}} ) {
 131         if ( any { /(^psgi|^plack)/i } keys %ENV ) {
 132             $borrower{$key} = ( $entry->{'is'} && $ENV{"HTTP_" . uc($entry->{'is'}) } ) || $entry->{'content'} || '';
 133         } else {
 134             $borrower{$key} = ( $entry->{'is'} && $ENV{ $entry->{'is'} } ) || $entry->{'content'} || '';
 135         }
 136     }
 137
 138     my $patron = Koha::Patron->new( \%borrower )->store;
 139     C4::Members::Messaging::SetMessagingPreferencesFromDefaults( { borrowernumber => $patron->borrowernumber, categorycode => $patron->categorycode } );
 140
 141     return ( 1, $patron->cardnumber, $patron->userid );
 142 }
 143
 144 sub _sync {
 145     my ($borrowernumber, $config, $match ) = @_;
 146     my %borrower;
 147     $borrower{'borrowernumber'} = $borrowernumber;
 148     while ( my ( $key, $entry ) = each %{$config->{'mapping'}} ) {
 149         if ( any { /(^psgi|^plack)/i } keys %ENV ) {
 150             $borrower{$key} = ( $entry->{'is'} && $ENV{"HTTP_" . uc($entry->{'is'}) } ) || $entry->{'content'} || '';
 151         } else {
 152             $borrower{$key} = ( $entry->{'is'} && $ENV{ $entry->{'is'} } ) || $entry->{'content'} || '';
 153         }
 154     }
 155     my $patron = Koha::Patrons->find( $borrowernumber );
 156     $patron->set(\%borrower)->store;
 157 }
 158
 159 sub _get_uri {
 160
 161     my $protocol = "https://";
 162     my $interface = C4::Context->interface;
 163     $debug and warn "shibboleth interface: " . $interface;
 164
 165     my $uri;
 166     if ( $interface eq 'intranet' ) {
 167
 168         $uri = C4::Context->preference('staffClientBaseURL') // '';
 169         if ($uri eq '') {
 170             $debug and warn 'staffClientBaseURL not set!';
 171         }
 172     } else {
 173         $uri = C4::Context->preference('OPACBaseURL') // '';
 174         if ($uri eq '') {
 175             $debug and warn 'OPACBaseURL not set!';
 176         }
 177     }
 178
 179     if ($uri =~ /(.*):\/\/(.*)/) {
 180         my $oldprotocol = $1;
 181         if ($oldprotocol ne 'https') {
 182             $debug
 183                 and warn
 184                   'Shibboleth requires OPACBaseURL/staffClientBaseURL to use the https protocol!';
 185         }
 186         $uri = $2;
 187     }
 188     my $return = $protocol . $uri;
 189     return $return;
 190 }
 191
 192 sub _get_shib_config {
 193     my $config = C4::Context->config('shibboleth');
 194
 195     if ( !$config ) {
 196         carp 'shibboleth config not defined' if $debug;
 197         return 0;
 198     }
 199
 200     if ( $config->{matchpoint}
 201         && defined( $config->{mapping}->{ $config->{matchpoint} }->{is} ) )
 202     {
 203         if ($debug) {
 204             warn "koha borrower field to match: " . $config->{matchpoint};
 205             warn "shibboleth attribute to match: "
 206               . $config->{mapping}->{ $config->{matchpoint} }->{is};
 207         }
 208         return $config;
 209     }
 210     else {
 211         if ( !$config->{matchpoint} ) {
 212             carp 'shibboleth matchpoint not defined';
 213         }
 214         else {
 215             carp 'shibboleth matchpoint not mapped';
 216         }
 217         return 0;
 218     }
 219 }
 220
 221 1;
 222 __END__
 223
 224 =head1 NAME
 225
 226 C4::Auth_with_shibboleth
 227
 228 =head1 SYNOPSIS
 229
 230 use C4::Auth_with_shibboleth;
 231
 232 =head1 DESCRIPTION
 233
 234 This module is specific to Shibboleth authentication in koha and relies heavily upon the native shibboleth service provider package in your operating system.
 235
 236 =head1 CONFIGURATION
 237
 238 To use this type of authentication these additional packages are required:
 239
 240 =over
 241
 242 =item *
 243
 244 libapache2-mod-shib2
 245
 246 =item *
 247
 248 libshibsp5:amd64
 249
 250 =item *
 251
 252 shibboleth-sp2-schemas
 253
 254 =back
 255
 256 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.
 257
 258 But to sum up, to get shibboleth working in koha, as a minimum you will need to:
 259
 260 =over
 261
 262 =item 1.
 263
 264 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)
 265
 266 =item 2.
 267
 268 Swap metadata with your Identidy Provider (IdP)
 269
 270 =item 3.
 271
 272 Map their attributes to what you want to see in koha
 273
 274 =item 4.
 275
 276 Tell apache that we wish to allow koha to authenticate via shibboleth.
 277
 278 This is as simple as adding the below to your virtualhost config (for CGI running):
 279
 280  <Location />
 281    AuthType shibboleth
 282    Require shibboleth
 283  </Location>
 284
 285 Or (for Plack running):
 286
 287  <Location />
 288    AuthType shibboleth
 289    Require shibboleth
 290    ShibUseEnvironment Off
 291    ShibUseHeaders On
 292  </Location>
 293
 294 IMPORTANT: Please note, if you are running in the plack configuration you should consult https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSpoofChecking for security advice regarding header spoof checking settings. (See also bug 17776 on Bugzilla about enabling ShibUseHeaders.)
 295
 296 =item 5.
 297
 298 Configure koha to listen for shibboleth environment variables.
 299
 300 This is as simple as enabling B<useshibboleth> in koha-conf.xml:
 301
 302  <useshibboleth>1</useshibboleth>
 303
 304 =item 6.
 305
 306 Map shibboleth attributes to koha fields, and configure authentication match point in koha-conf.xml.
 307
 308  <shibboleth>
 309    <matchpoint>userid</matchpoint> <!-- koha borrower field to match upon -->
 310    <mapping>
 311      <userid is="eduPersonID"></userid> <!-- koha borrower field to shibboleth attribute mapping -->
 312    </mapping>
 313  </shibboleth>
 314
 315 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.
 316
 317 =back
 318
 319 It should be as simple as that; you should now be able to login via shibboleth in the opac.
 320
 321 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>
 322
 323 =head1 FUNCTIONS
 324
 325 =head2 logout_shib
 326
 327 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.
 328
 329   logout_shib($query);
 330
 331 =head2 login_shib_url
 332
 333 Given a query, this will return a shibboleth login url with return code to page with given given query.
 334
 335   my $shibLoginURL = login_shib_url($query);
 336
 337 =head2 get_login_shib
 338
 339 Returns the shibboleth login attribute should it be found present in the http session
 340
 341   my $shib_login = get_login_shib();
 342
 343 =head2 checkpw_shib
 344
 345 Given 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.
 346
 347   my ( $retval, $retcard, $retuserid ) = C4::Auth_with_shibboleth::checkpw_shib( $shib_login );
 348
 349 =head2 _get_uri
 350
 351   _get_uri();
 352
 353 A sugar function to that simply returns the current page URI with appropriate protocol attached
 354
 355 This routine is NOT exported
 356
 357 =head2 _get_shib_config
 358
 359   my $config = _get_shib_config();
 360
 361 A sugar function that checks for a valid shibboleth configuration, and if found returns a hashref of it's contents
 362
 363 This routine is NOT exported
 364
 365 =head2 _autocreate
 366
 367   my ( $retval, $retcard, $retuserid ) = _autocreate( $config, $match );
 368
 369 Given a shibboleth attribute reference and a userid this internal routine will add the given user to Koha and return their user credentials.
 370
 371 This routine is NOT exported
 372
 373 =head1 SEE ALSO
 374
 375 =cut