1 package C4::Auth_with_shibboleth;
3 # Copyright 2014 PTFS Europe
5 # This file is part of Koha.
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.
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.
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>.
24 use Koha::AuthUtils qw(get_script_name);
27 use C4::Members::Messaging;
30 use List::Util qw(any);
32 use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $debug);
39 qw(shib_ok logout_shib login_shib_url checkpw_shib get_login_shib);
42 # Check that shib config is not malformed
44 my $config = _get_shib_config();
53 # Logout from Shibboleth
57 print $query->redirect( $uri . "/Shibboleth.sso/Logout?return=$uri" );
60 # Returns Shibboleth login URL with callback to the requesting URL
64 my $param = _get_uri() . get_script_name();
65 if ( $query->query_string() ) {
66 $param = $param . '%3F' . $query->query_string();
68 my $uri = _get_uri() . "/Shibboleth.sso/Login?target=$param";
72 # Returns shibboleth user login
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
79 # Shibboleth attributes are mapped into http environmement variables, so we're getting
80 # the match point of the user this way
82 # Get shibboleth config
83 my $config = _get_shib_config();
85 my $matchAttribute = $config->{mapping}->{ $config->{matchpoint} }->{is};
87 if ( any { /(^psgi|^plack)/i } keys %ENV ) {
88 $debug and warn $matchAttribute . " value: " . $ENV{"HTTP_".uc($matchAttribute)};
89 return $ENV{"HTTP_".uc($matchAttribute)} || '';
91 $debug and warn $matchAttribute . " value: " . $ENV{$matchAttribute};
92 return $ENV{$matchAttribute} || '';
96 # Checks for password correctness
97 # In our case : does the given attribute match one of our users ?
99 $debug and warn "checkpw_shib";
102 my $config = _get_shib_config();
103 $debug and warn "User Shibboleth-authenticated as: $match";
105 # Does the given shibboleth attribute value ($match) match a valid koha user ?
107 Koha::Database->new()->schema()->resultset('Borrower')
108 ->find( { $config->{matchpoint} => $match } );
109 if ( defined($borrower) ) {
110 return ( 1, $borrower->get_column('cardnumber'), $borrower->get_column('userid') );
113 if ( $config->{'autocreate'} ) {
114 return _autocreate( $config, $match );
116 # If we reach this point, the user is not a valid koha user
117 $debug and warn "User with $config->{matchpoint} of $match is not a valid Koha user";
123 my ( $config, $match ) = @_;
125 my %borrower = ( $config->{matchpoint} => $match );
127 while ( my ( $key, $entry ) = each %{$config->{'mapping'}} ) {
128 $borrower{$key} = ( $entry->{'is'} && $ENV{ $entry->{'is'} } ) || $entry->{'content'} || '';
131 my $patron = Koha::Patron->new( \%borrower )->store;
132 C4::Members::Messaging::SetMessagingPreferencesFromDefaults( { borrowernumber => $patron->borrowernumber, categorycode => $patron->categorycode } );
134 return ( 1, $patron->cardnumber, $patron->userid );
139 my $protocol = "https://";
140 my $interface = C4::Context->interface;
141 $debug and warn "shibboleth interface: " . $interface;
144 if ( $interface eq 'intranet' ) {
146 $uri = C4::Context->preference('staffClientBaseURL') // '';
148 $debug and warn 'staffClientBaseURL not set!';
151 $uri = C4::Context->preference('OPACBaseURL') // '';
153 $debug and warn 'OPACBaseURL not set!';
157 if ($uri =~ /(.*):\/\/(.*)/) {
158 my $oldprotocol = $1;
159 if ($oldprotocol ne 'https') {
162 'Shibboleth requires OPACBaseURL/staffClientBaseURL to use the https protocol!';
166 my $return = $protocol . $uri;
170 sub _get_shib_config {
171 my $config = C4::Context->config('shibboleth');
174 carp 'shibboleth config not defined';
178 if ( $config->{matchpoint}
179 && defined( $config->{mapping}->{ $config->{matchpoint} }->{is} ) )
182 warn "koha borrower field to match: " . $config->{matchpoint};
183 warn "shibboleth attribute to match: "
184 . $config->{mapping}->{ $config->{matchpoint} }->{is};
189 if ( !$config->{matchpoint} ) {
190 carp 'shibboleth matchpoint not defined';
193 carp 'shibboleth matchpoint not mapped';
204 C4::Auth_with_shibboleth
208 use C4::Auth_with_shibboleth;
212 This module is specific to Shibboleth authentication in koha and relies heavily upon the native shibboleth service provider package in your operating system.
216 To use this type of authentication these additional packages are required:
230 shibboleth-sp2-schemas
234 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.
236 But to sum up, to get shibboleth working in koha, as a minimum you will need to:
242 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)
246 Swap metadata with your Identidy Provider (IdP)
250 Map their attributes to what you want to see in koha
254 Tell apache that we wish to allow koha to authenticate via shibboleth.
256 This is as simple as adding the below to your virtualhost config (for CGI running):
263 Or (for Plack running):
268 ShibUseEnvironment Off
274 Configure koha to listen for shibboleth environment variables.
276 This is as simple as enabling B<useshibboleth> in koha-conf.xml:
278 <useshibboleth>1</useshibboleth>
282 Map shibboleth attributes to koha fields, and configure authentication match point in koha-conf.xml.
285 <matchpoint>userid</matchpoint> <!-- koha borrower field to match upon -->
287 <userid is="eduPersonID"></userid> <!-- koha borrower field to shibboleth attribute mapping -->
291 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.
295 It should be as simple as that; you should now be able to login via shibboleth in the opac.
297 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>
303 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.
307 =head2 login_shib_url
309 Given a query, this will return a shibboleth login url with return code to page with given given query.
311 my $shibLoginURL = login_shib_url($query);
313 =head2 get_login_shib
315 Returns the shibboleth login attribute should it be found present in the http session
317 my $shib_login = get_login_shib();
321 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.
323 my ( $retval, $retcard, $retuserid ) = C4::Auth_with_shibboleth::checkpw_shib( $shib_login );
329 A sugar function to that simply returns the current page URI with appropriate protocol attached
331 This routine is NOT exported
333 =head2 _get_shib_config
335 my $config = _get_shib_config();
337 A sugar function that checks for a valid shibboleth configuration, and if found returns a hashref of it's contents
339 This routine is NOT exported
343 my ( $retval, $retcard, $retuserid ) = _autocreate( $config, $match );
345 Given a shibboleth attribute reference and a userid this internal routine will add the given user to Koha and return their user credentials.
347 This routine is NOT exported