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 Carp;
  27 use CGI;
  28
  29 use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $debug);
  30
  31 BEGIN {
  32     require Exporter;
  33     $debug   = $ENV{DEBUG};
  34     @ISA     = qw(Exporter);
  35     @EXPORT =
  36       qw(shib_ok logout_shib login_shib_url checkpw_shib get_login_shib);
  37 }
  38
  39 # Check that shib config is not malformed
  40 sub shib_ok {
  41     my $config = _get_shib_config();
  42
  43     if ($config) {
  44         return 1;
  45     }
  46
  47     return 0;
  48 }
  49
  50 # Logout from Shibboleth
  51 sub logout_shib {
  52     my ($query) = @_;
  53     my $uri = _get_uri();
  54     print $query->redirect( $uri . "/Shibboleth.sso/Logout?return=$uri" );
  55 }
  56
  57 # Returns Shibboleth login URL with callback to the requesting URL
  58 sub login_shib_url {
  59     my ($query) = @_;
  60
  61     my $param = _get_uri() . get_script_name();
  62     if ( $query->query_string() ) {
  63         $param = $param . '%3F' . $query->query_string();
  64     }
  65     my $uri = _get_uri() . "/Shibboleth.sso/Login?target=$param";
  66     return $uri;
  67 }
  68
  69 # Returns shibboleth user login
  70 sub get_login_shib {
  71
  72 # In case of a Shibboleth authentication, we expect a shibboleth user attribute
  73 # to contain the login match point of the shibboleth-authenticated user. This match
  74 # point is configured in koha-conf.xml
  75
  76 # Shibboleth attributes are mapped into http environmement variables, so we're getting
  77 # the match point of the user this way
  78
  79     # Get shibboleth config
  80     my $config = _get_shib_config();
  81
  82     my $matchAttribute = $config->{mapping}->{ $config->{matchpoint} }->{is};
  83     $debug and warn $matchAttribute . " value: " . $ENV{$matchAttribute};
  84
  85     return $ENV{$matchAttribute} || '';
  86 }
  87
  88 # Checks for password correctness
  89 # In our case : does the given attribute match one of our users ?
  90 sub checkpw_shib {
  91     $debug and warn "checkpw_shib";
  92
  93     my ( $match ) = @_;
  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 $borrower =
  99       Koha::Database->new()->schema()->resultset('Borrower')
 100       ->find( { $config->{matchpoint} => $match } );
 101     if ( defined($borrower) ) {
 102         return ( 1, $borrower->get_column('cardnumber'), $borrower->get_column('userid') );
 103     }
 104
 105     # If we reach this point, the user is not a valid koha user
 106     $debug
 107       and warn
 108       "User with $config->{matchpoint} of $match is not a valid Koha user";
 109     return 0;
 110 }
 111
 112 sub _get_uri {
 113
 114     my $protocol = "https://";
 115
 116     my $uri = C4::Context->preference('OPACBaseURL') // '';
 117     if ($uri eq '') {
 118         $debug and warn 'OPACBaseURL not set!';
 119     }
 120     if ($uri =~ /(.*):\/\/(.*)/) {
 121         my $oldprotocol = $1;
 122         if ($oldprotocol ne 'https') {
 123             $debug
 124                 and warn
 125                   'Shibboleth requires OPACBaseURL to use the https protocol!';
 126         }
 127         $uri = $2;
 128     }
 129
 130     my $return = $protocol . $uri;
 131     return $return;
 132 }
 133
 134 sub _get_shib_config {
 135     my $config = C4::Context->config('shibboleth');
 136
 137     if ( !$config ) {
 138         carp 'shibboleth config not defined';
 139         return 0;
 140     }
 141
 142     if ( $config->{matchpoint}
 143         && defined( $config->{mapping}->{ $config->{matchpoint} }->{is} ) )
 144     {
 145         if ($debug) {
 146             warn "koha borrower field to match: " . $config->{matchpoint};
 147             warn "shibboleth attribute to match: "
 148               . $config->{mapping}->{ $config->{matchpoint} }->{is};
 149         }
 150         return $config;
 151     }
 152     else {
 153         if ( !$config->{matchpoint} ) {
 154             carp 'shibboleth matchpoint not defined';
 155         }
 156         else {
 157             carp 'shibboleth matchpoint not mapped';
 158         }
 159         return 0;
 160     }
 161 }
 162
 163 1;
 164 __END__
 165
 166 =head1 NAME
 167
 168 C4::Auth_with_shibboleth
 169
 170 =head1 SYNOPSIS
 171
 172 use C4::Auth_with_shibboleth;
 173
 174 =head1 DESCRIPTION
 175
 176 This module is specific to Shibboleth authentication in koha and relies heavily upon the native shibboleth service provider package in your operating system.
 177
 178 =head1 CONFIGURATION
 179
 180 To use this type of authentication these additional packages are required:
 181
 182 =over
 183
 184 =item *
 185
 186 libapache2-mod-shib2
 187
 188 =item *
 189
 190 libshibsp5:amd64
 191
 192 =item *
 193
 194 shibboleth-sp2-schemas
 195
 196 =back
 197
 198 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.
 199
 200 But to sum up, to get shibboleth working in koha, as a minimum you will need to:
 201
 202 =over
 203
 204 =item 1.
 205
 206 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)
 207
 208 =item 2.
 209
 210 Swap metadata with your Identidy Provider (IdP)
 211
 212 =item 3.
 213
 214 Map their attributes to what you want to see in koha
 215
 216 =item 4.
 217
 218 Tell apache that we wish to allow koha to authenticate via shibboleth.
 219
 220 This is as simple as adding the below to your virtualhost config:
 221
 222  <Location />
 223    AuthType shibboleth
 224    Require shibboleth
 225  </Location>
 226
 227 =item 5.
 228
 229 Configure koha to listen for shibboleth environment variables.
 230
 231 This is as simple as enabling B<useshibboleth> in koha-conf.xml:
 232
 233  <useshibboleth>1</useshibboleth>
 234
 235 =item 6.
 236
 237 Map shibboleth attributes to koha fields, and configure authentication match point in koha-conf.xml.
 238
 239  <shibboleth>
 240    <matchpoint>userid<matchpoint> <!-- koha borrower field to match upon -->
 241    <mapping>
 242      <userid is="eduPersonID"></userid> <!-- koha borrower field to shibboleth attribute mapping -->
 243    </mapping>
 244  </shibboleth>
 245
 246 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.
 247
 248 =back
 249
 250 It should be as simple as that; you should now be able to login via shibboleth in the opac.
 251
 252 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>
 253
 254 =head1 FUNCTIONS
 255
 256 =head2 logout_shib
 257
 258 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.
 259
 260   logout_shib($query);
 261
 262 =head2 login_shib_url
 263
 264 Given a query, this will return a shibboleth login url with return code to page with given given query.
 265
 266   my $shibLoginURL = login_shib_url($query);
 267
 268 =head2 get_login_shib
 269
 270 Returns the shibboleth login attribute should it be found present in the http session
 271
 272   my $shib_login = get_login_shib();
 273
 274 =head2 checkpw_shib
 275
 276 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.
 277
 278   my ( $retval, $retcard, $retuserid ) = C4::Auth_with_shibboleth::checkpw_shib( $shib_login );
 279
 280 =head1 SEE ALSO
 281
 282 =cut