1 package C4::Auth_with_shibboleth;
3 # Copyright 2011 BibLibre
5 # This file is part of Koha.
7 # Koha is free software; you can redistribute it and/or modify it under the
8 # terms of the GNU General Public License as published by the Free Software
9 # Foundation; either version 2 of the License, or (at your option) any later
12 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
13 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
14 # A PARTICULAR PURPOSE. See the GNU General Public License for more details.
16 # You should have received a copy of the GNU General Public License along
17 # with Koha; if not, write to the Free Software Foundation, Inc.,
18 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
28 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $debug);
32 $VERSION = 3.03; # set the version for version checking
35 @EXPORT = qw(shib_ok logout_shib login_shib_url checkpw_shib get_login_shib);
38 # Check that shib config is not malformed
40 my $config = _get_shib_config();
49 # Logout from Shibboleth
53 print $query->redirect( $uri . "/Shibboleth.sso/Logout?return=$uri" );
56 # Returns Shibboleth login URL with callback to the requesting URL
60 my $param = _get_uri() . $query->script_name();
61 if ( $query->query_string() ) {
62 $param = $param . '%3F' . $query->query_string();
64 my $uri = _get_uri() . "/Shibboleth.sso/Login?target=$param";
68 # Returns shibboleth user login
71 # In case of a Shibboleth authentication, we expect a shibboleth user attribute
72 # to contain the login match point of the shibboleth-authenticated user. This match
73 # point is configured in koha-conf.xml
75 # Shibboleth attributes are mapped into http environmement variables, so we're getting
76 # the match point of the user this way
78 # Get shibboleth config
79 my $config = _get_shib_config();
81 my $matchAttribute = $config->{mapping}->{ $config->{matchpoint} }->{is};
82 $debug and warn $matchAttribute . " value: " . $ENV{ $matchAttribute };
84 return $ENV{ $matchAttribute } || '';
87 # Checks for password correctness
88 # In our case : does the given attribute match one of our users ?
90 $debug and warn "checkpw_shib";
92 my ( $dbh, $match ) = @_;
93 my ( $retnumber, $userid );
94 my $config = _get_shib_config();
95 $debug and warn "User Shibboleth-authenticated as: $match";
97 # Does the given shibboleth attribute value ($match) match a valid koha user ?
98 my $sth = $dbh->prepare("select cardnumber, userid from borrowers where $config->{matchpoint}=?");
99 $sth->execute($match);
101 my @retvals = $sth->fetchrow;
102 $retnumber = $retvals[0];
103 $userid = $retvals[1];
104 return ( 1, $retnumber, $userid );
107 # If we reach this point, the user is not a valid koha user
108 $debug and warn "User with $config->{matchpoint} of $match is not a valid Koha user";
114 my $protocol = "https://";
116 my $return = $protocol . C4::Context->preference('OPACBaseURL');
120 sub _get_shib_config {
121 my $config = C4::Context->config('shibboleth');
124 carp 'shibboleth config not defined';
128 if ( $config->{matchpoint}
129 && defined( $config->{mapping}->{ $config->{matchpoint} }->{is} ) )
132 warn "koha borrower field to match: " . $config->{matchpoint};
133 warn "shibboleth attribute to match: "
134 . $config->{mapping}->{ $config->{matchpoint} }->{is};
139 if ( !$config->{matchpoint} ) {
140 carp 'shibboleth matchpoint not defined';
143 carp 'shibboleth matchpoint not mapped';
154 C4::Auth_with_shibboleth
158 use C4::Auth_with_shibboleth;
162 This module is specific to Shibboleth authentication in koha and relies heavily upon the native shibboleth service provider package in your operating system.
166 To use this type of authentication these additional packages are required:
180 shibboleth-sp2-schemas
184 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.
186 But to sum up, to get shibboleth working in koha, as a minimum you will need to:
192 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)
196 Swap metadata with your Identidy Provider (IdP)
200 Map their attributes to what you want to see in koha
204 Tell apache that we wish to allow koha to authenticate via shibboleth.
206 This is as simple as adding the below to your virtualhost config:
215 Configure koha to listen for shibboleth environment variables.
217 This is as simple as enabling B<useshibboleth> in koha-conf.xml:
219 <useshibboleth>1</useshibboleth>
223 Map shibboleth attributes to koha fields, and configure authentication match point in koha-conf.xml.
226 <matchpoint>userid<matchpoint> <!-- koha borrower field to match upon -->
228 <userid is="eduPersonID"></userid> <!-- koha borrower field to shibboleth attribute mapping -->
232 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.
236 It should be as simple as that; you should now be able to login via shibboleth in the opac.
238 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 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.
248 =head2 login_shib_url
250 Given a query, this will return a shibboleth login url with return code to page with given given query.
252 my $shibLoginURL = login_shib_url($query);
254 =head2 get_login_shib
256 Returns the shibboleth login attribute should it be found present in the http session
258 my $shib_login = get_login_shib();
262 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.
264 my ( $retval, $retcard, $retuserid ) = C4::Auth_with_shibboleth::checkpw_shib( $dbh, $shib_login );