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
  31 use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $debug);
  32
  33 BEGIN {
  34     require Exporter;
  35     $debug   = $ENV{DEBUG};
  36     @ISA     = qw(Exporter);
  37     @EXPORT =
  38       qw(shib_ok logout_shib login_shib_url checkpw_shib get_login_shib);
  39 }
  40
  41 # Check that shib config is not malformed
  42 sub shib_ok {
  43     my $config = _get_shib_config();
  44
  45     if ($config) {
  46         return 1;
  47     }
  48
  49     return 0;
  50 }
  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     $debug and warn $matchAttribute . " value: " . $ENV{$matchAttribute};
  87
  88     return $ENV{$matchAttribute} || '';
  89 }
  90
  91 # Checks for password correctness
  92 # In our case : does the given attribute match one of our users ?
  93 sub checkpw_shib {
  94     $debug and warn "checkpw_shib";
  95
  96     my ( $match ) = @_;
  97     my $config = _get_shib_config();
  98     $debug and warn "User Shibboleth-authenticated as: $match";
  99
 100     # Does the given shibboleth attribute value ($match) match a valid koha user ?
 101     my $borrower =
 102       Koha::Database->new()->schema()->resultset('Borrower')
 103       ->find( { $config->{matchpoint} => $match } );
 104     if ( defined($borrower) ) {
 105         return ( 1, $borrower->get_column('cardnumber'), $borrower->get_column('userid') );
 106     }
 107
 108     if ( $config->{'autocreate'} ) {
 109         return _autocreate( $config, $match );
 110     } else {
 111         # If we reach this point, the user is not a valid koha user
 112          $debug and warn "User with $config->{matchpoint} of $match is not a valid Koha user";
 113         return 0;
 114     }
 115 }
 116
 117 sub _autocreate {
 118     my ( $config, $match ) = @_;
 119
 120     my %borrower = ( $config->{matchpoint} => $match );
 121
 122     while ( my ( $key, $entry ) = each %{$config->{'mapping'}} ) {
 123         $borrower{$key} = ( $entry->{'is'} && $ENV{ $entry->{'is'} } ) || $entry->{'content'} || '';
 124     }
 125
 126     my $patron = Koha::Patron->new( \%borrower )->store;
 127     C4::Members::Messaging::SetMessagingPreferencesFromDefaults( { borrowernumber => $patron->borrowernumber, categorycode => $patron->categorycode } );
 128
 129     return ( 1, $patron->cardnumber, $patron->userid );
 130 }
 131
 132 sub _get_uri {
 133
 134     my $protocol = "https://";
 135     my $interface = C4::Context->interface;
 136     $debug and warn "shibboleth interface: " . $interface;
 137
 138     my $return;
 139     my $uri;
 140     if ( $interface eq 'intranet' ) {
 141
 142         $uri = C4::Context->preference('staffClientBaseURL') // '';
 143         if ($uri eq '') {
 144             $debug and warn 'staffClientBaseURL not set!';
 145         }
 146     } else {
 147         $uri = C4::Context->preference('OPACBaseURL') // '';
 148         if ($uri eq '') {
 149             $debug and warn 'OPACBaseURL not set!';
 150         }
 151     }
 152
 153     if ($uri =~ /(.*):\/\/(.*)/) {
 154         my $oldprotocol = $1;
 155         if ($oldprotocol ne 'https') {
 156             $debug
 157                 and warn
 158                   'Shibboleth requires OPACBaseURL/staffClientBaseURL to use the https protocol!';
 159         }
 160         $uri = $2;
 161     }
 162     my $return = $protocol . $uri;
 163     return $return;
 164 }
 165
 166 sub _get_shib_config {
 167     my $config = C4::Context->config('shibboleth');
 168
 169     if ( !$config ) {
 170         carp 'shibboleth config not defined';
 171         return 0;
 172     }
 173
 174     if ( $config->{matchpoint}
 175         && defined( $config->{mapping}->{ $config->{matchpoint} }->{is} ) )
 176     {
 177         if ($debug) {
 178             warn "koha borrower field to match: " . $config->{matchpoint};
 179             warn "shibboleth attribute to match: "
 180               . $config->{mapping}->{ $config->{matchpoint} }->{is};
 181         }
 182         return $config;
 183     }
 184     else {
 185         if ( !$config->{matchpoint} ) {
 186             carp 'shibboleth matchpoint not defined';
 187         }
 188         else {
 189             carp 'shibboleth matchpoint not mapped';
 190         }
 191         return 0;
 192     }
 193 }
 194
 195 1;
 196 __END__
 197
 198 =head1 NAME
 199
 200 C4::Auth_with_shibboleth
 201
 202 =head1 SYNOPSIS
 203
 204 use C4::Auth_with_shibboleth;
 205
 206 =head1 DESCRIPTION
 207
 208 This module is specific to Shibboleth authentication in koha and relies heavily upon the native shibboleth service provider package in your operating system.
 209
 210 =head1 CONFIGURATION
 211
 212 To use this type of authentication these additional packages are required:
 213
 214 =over
 215
 216 =item *
 217
 218 libapache2-mod-shib2
 219
 220 =item *
 221
 222 libshibsp5:amd64
 223
 224 =item *
 225
 226 shibboleth-sp2-schemas
 227
 228 =back
 229
 230 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.
 231
 232 But to sum up, to get shibboleth working in koha, as a minimum you will need to:
 233
 234 =over
 235
 236 =item 1.
 237
 238 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)
 239
 240 =item 2.
 241
 242 Swap metadata with your Identidy Provider (IdP)
 243
 244 =item 3.
 245
 246 Map their attributes to what you want to see in koha
 247
 248 =item 4.
 249
 250 Tell apache that we wish to allow koha to authenticate via shibboleth.
 251
 252 This is as simple as adding the below to your virtualhost config:
 253
 254  <Location />
 255    AuthType shibboleth
 256    Require shibboleth
 257  </Location>
 258
 259 =item 5.
 260
 261 Configure koha to listen for shibboleth environment variables.
 262
 263 This is as simple as enabling B<useshibboleth> in koha-conf.xml:
 264
 265  <useshibboleth>1</useshibboleth>
 266
 267 =item 6.
 268
 269 Map shibboleth attributes to koha fields, and configure authentication match point in koha-conf.xml.
 270
 271  <shibboleth>
 272    <matchpoint>userid</matchpoint> <!-- koha borrower field to match upon -->
 273    <mapping>
 274      <userid is="eduPersonID"></userid> <!-- koha borrower field to shibboleth attribute mapping -->
 275    </mapping>
 276  </shibboleth>
 277
 278 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.
 279
 280 =back
 281
 282 It should be as simple as that; you should now be able to login via shibboleth in the opac.
 283
 284 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>
 285
 286 =head1 FUNCTIONS
 287
 288 =head2 logout_shib
 289
 290 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.
 291
 292   logout_shib($query);
 293
 294 =head2 login_shib_url
 295
 296 Given a query, this will return a shibboleth login url with return code to page with given given query.
 297
 298   my $shibLoginURL = login_shib_url($query);
 299
 300 =head2 get_login_shib
 301
 302 Returns the shibboleth login attribute should it be found present in the http session
 303
 304   my $shib_login = get_login_shib();
 305
 306 =head2 checkpw_shib
 307
 308 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.
 309
 310   my ( $retval, $retcard, $retuserid ) = C4::Auth_with_shibboleth::checkpw_shib( $shib_login );
 311
 312 =head2 _autocreate
 313
 314   my ( $retval, $retcard, $retuserid ) = _autocreate( $config, $match );
 315
 316 Given a shibboleth attribute reference and a userid this internal routine will add the given user to Koha and return their user credentials.
 317
 318 This routine is NOT exported
 319
 320 =head1 SEE ALSO
 321
 322 =cut