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