NAME

C4::Auth_with_shibboleth

SYNOPSIS

use C4::Auth_with_shibboleth;

DESCRIPTION

This module is specific to Shibboleth authentication in koha and relies heavily upon the native shibboleth service provider package in your operating system.

CONFIGURATION

To use this type of authentication these additional packages are required:

libapache2-mod-shib2
libshibsp5:amd64
shibboleth-sp2-schemas

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.

But to sum up, to get shibboleth working in koha, as a minimum you will need to:

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)
Swap metadata with your Identidy Provider (IdP)
Map their attributes to what you want to see in koha
Tell apache that we wish to allow koha to authenticate via shibboleth.
This is as simple as adding the below to your virtualhost config (for CGI running):
```
 <Location />
   AuthType shibboleth
   Require shibboleth
 </Location>
```
Or (for Plack running):
```
 <Location />
   AuthType shibboleth
   Require shibboleth
   ShibUseEnvironment Off
   ShibUseHeaders On
 </Location>
```
IMPORTANT: Please note, if you are running in the plack configuration you should consult https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSpoofChecking for security advice regarding header spoof checking settings. (See also bug 17776 on Bugzilla about enabling ShibUseHeaders.)
Configure koha to listen for shibboleth environment variables.
This is as simple as enabling useshibboleth in koha-conf.xml:
```
 <useshibboleth>1</useshibboleth>
```
Map shibboleth attributes to koha fields, and configure authentication match point in koha-conf.xml.
```
 <shibboleth>
   <matchpoint>userid</matchpoint> 
   <mapping>
     <userid is="eduPersonID"></userid> 
   </mapping>
 </shibboleth>
```
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.

It should be as simple as that; you should now be able to login via shibboleth in the opac.

If you need more help configuring your Service Provider to authenticate against a chosen Identity Provider then it might be worth taking a look at the community wiki page

FUNCTIONS

logout_shib

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.

  logout_shib($query);

login_shib_url

Given a query, this will return a shibboleth login url with return code to page with given given query.

  my $shibLoginURL = login_shib_url($query);

get_login_shib

Returns the shibboleth login attribute should it be found present in the http session

  my $shib_login = get_login_shib();

checkpw_shib

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.

  my ( $retval, $retcard, $retuserid ) = C4::Auth_with_shibboleth::checkpw_shib( $shib_login );

_get_uri

  _get_uri();

A sugar function to that simply returns the current page URI with appropriate protocol attached

This routine is NOT exported

_get_shib_config

  my $config = _get_shib_config();

A sugar function that checks for a valid shibboleth configuration, and if found returns a hashref of it's contents

This routine is NOT exported

_autocreate

  my ( $retval, $retcard, $retuserid ) = _autocreate( $config, $match );

Given a shibboleth attribute reference and a userid this internal routine will add the given user to Koha and return their user credentials.

This routine is NOT exported