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 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 =
  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() . $query->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 ( $dbh, $match ) = @_;
  94     my ( $retnumber, $userid );
  95     my $config = _get_shib_config();
  96     $debug and warn "User Shibboleth-authenticated as: $match";
  97
  98   # Does the given shibboleth attribute value ($match) match a valid koha user ?
  99     my $sth = $dbh->prepare(
 100         "select cardnumber, userid from borrowers where $config->{matchpoint}=?"
 101     );
 102     $sth->execute($match);
 103     if ( $sth->rows ) {
 104         my @retvals = $sth->fetchrow;
 105         $retnumber = $retvals[0];
 106         $userid    = $retvals[1];
 107         return ( 1, $retnumber, $userid );
 108     }
 109
 110     # If we reach this point, the user is not a valid koha user
 111     $debug
 112       and warn
 113       "User with $config->{matchpoint} of $match is not a valid Koha user";
 114     return 0;
 115 }
 116
 117 sub _get_uri {
 118
 119     my $protocol = "https://";
 120
 121     my $return = $protocol . C4::Context->preference('OPACBaseURL');
 122     return $return;
 123 }
 124
 125 sub _get_shib_config {
 126     my $config = C4::Context->config('shibboleth');
 127
 128     if ( !$config ) {
 129         carp 'shibboleth config not defined';
 130         return 0;
 131     }
 132
 133     if ( $config->{matchpoint}
 134         && defined( $config->{mapping}->{ $config->{matchpoint} }->{is} ) )
 135     {
 136         if ($debug) {
 137             warn "koha borrower field to match: " . $config->{matchpoint};
 138             warn "shibboleth attribute to match: "
 139               . $config->{mapping}->{ $config->{matchpoint} }->{is};
 140         }
 141         return $config;
 142     }
 143     else {
 144         if ( !$config->{matchpoint} ) {
 145             carp 'shibboleth matchpoint not defined';
 146         }
 147         else {
 148             carp 'shibboleth matchpoint not mapped';
 149         }
 150         return 0;
 151     }
 152 }
 153
 154 1;
 155 __END__
 156
 157 =head1 NAME
 158
 159 C4::Auth_with_shibboleth
 160
 161 =head1 SYNOPSIS
 162
 163 use C4::Auth_with_shibboleth;
 164
 165 =head1 DESCRIPTION
 166
 167 This module is specific to Shibboleth authentication in koha and relies heavily upon the native shibboleth service provider package in your operating system.
 168
 169 =head1 CONFIGURATION
 170
 171 To use this type of authentication these additional packages are required:
 172
 173 =over
 174
 175 =item *
 176
 177 libapache2-mod-shib2
 178
 179 =item *
 180
 181 libshibsp5:amd64
 182
 183 =item *
 184
 185 shibboleth-sp2-schemas
 186
 187 =back
 188
 189 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.
 190
 191 But to sum up, to get shibboleth working in koha, as a minimum you will need to:
 192
 193 =over
 194
 195 =item 1.
 196
 197 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)
 198
 199 =item 2.
 200
 201 Swap metadata with your Identidy Provider (IdP)
 202
 203 =item 3.
 204
 205 Map their attributes to what you want to see in koha
 206
 207 =item 4.
 208
 209 Tell apache that we wish to allow koha to authenticate via shibboleth.
 210
 211 This is as simple as adding the below to your virtualhost config:
 212
 213  <Location />
 214    AuthType shibboleth
 215    Require shibboleth
 216  </Location>
 217
 218 =item 5.
 219
 220 Configure koha to listen for shibboleth environment variables.
 221
 222 This is as simple as enabling B<useshibboleth> in koha-conf.xml:
 223
 224  <useshibboleth>1</useshibboleth>
 225
 226 =item 6.
 227
 228 Map shibboleth attributes to koha fields, and configure authentication match point in koha-conf.xml.
 229
 230  <shibboleth>
 231    <matchpoint>userid<matchpoint> <!-- koha borrower field to match upon -->
 232    <mapping>
 233      <userid is="eduPersonID"></userid> <!-- koha borrower field to shibboleth attribute mapping -->
 234    </mapping>
 235  </shibboleth>
 236
 237 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.
 238
 239 =back
 240
 241 It should be as simple as that; you should now be able to login via shibboleth in the opac.
 242
 243 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>
 244
 245 =head1 FUNCTIONS
 246
 247 =head2 logout_shib
 248
 249 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.
 250
 251   logout_shib($query);
 252
 253 =head2 login_shib_url
 254
 255 Given a query, this will return a shibboleth login url with return code to page with given given query.
 256
 257   my $shibLoginURL = login_shib_url($query);
 258
 259 =head2 get_login_shib
 260
 261 Returns the shibboleth login attribute should it be found present in the http session
 262
 263   my $shib_login = get_login_shib();
 264
 265 =head2 checkpw_shib
 266
 267 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.
 268
 269   my ( $retval, $retcard, $retuserid ) = C4::Auth_with_shibboleth::checkpw_shib( $dbh, $shib_login );
 270
 271 =head1 SEE ALSO
 272
 273 =cut