Testing SSO

=WARNING=
This page is still under development. Do not rely on it for your testing.
=Overview=
In koha-testing-docker we include Keycloak, an open source identity and access management solution, to test single-sign on (SSO).
When using koha-testing-docker, include the docker-compose.sso.yml file when you want to use Keycloak.
=Keycloak=
=== Login ===
# Go to http://sso:8082/auth/admin
# Login using the credentials from docker-compose.sso.yml
=== Create Realm ===
# In the top left corner, click "master", then click "Create Realm"
# Type "test" into "Realm name" then click "Create"
# On the left side, click "Realm settings"
# Click the links for "OpenID Endpoint Configuration" and "SAML 2.0 Identity Provider Metadata"
=== Create User ===
# On the left side, click "Users"
# Click "Create new user"
# At "Username" type "kohadev"
# At "Email", type "kohadev@koha-community.org"
# At "First name", type "Koha"
# At "Last name", type "Dev"
# Click "Create"
# Click "Credentials"
# Click "Set password"
# Choose a password for your user and fill in "Password" and "Password confirmation"
# Change the "Temporary" slider from "On" to "Off"
# Click "Save"
# Click "Save password"
=== Create client: OpenID Connect ===
# On the left side, click "Clients"
# Click "Create client"
# At "Client ID", type "kohaoidc"
# Click "Next"
# Change the "Client authentication" slider from "Off" to "On"
# Click "Next"
# Scroll down to "Valid redirect URIs"
# Add relevant URIs
## e.g. http://localhost:8080/*
## e.g. http://localhost:8081/*
# Click "Save"
===Create client: SAML===
# N/A (this is handled later in the process)
=== Extra Notes ===
# To log in to a user account in the "test" realm, use an Incognito browser to visit http://sso:8082/auth/realms/test/account/#/
= Koha =
=== OpenID Connect ===
# Go to http://localhost:8081/
# Log into the Koha staff interface
# Go to http://localhost:8081/cgi-bin/koha/admin/identity_providers.pl
# Click "New identity provider"
# At "Code", type "test"
# At "Description", type "Test"
# At "Protocol", choose "OIDC"
# Click "Add default OIDC configuration"
# Replace "<enter client id>" with "kohaoidc"
# Go to Keycloak
## On the left side, click "Clients"
## Choose "kohaoidc"
## Click "Credentials"
## Click the "eyeball icon" next to "Client secret"
## Copy the unmasked data and go back to Koha
# Replace "<enter client secret>" with copied data from previous step
# Go to Keycloak
## On the left side, click "Realm settings"
## Click "OpenID Endpoint Configuration"
## Copy this URL (e.g. http://sso:8082/auth/realms/test/.well-known/openid-configuration)
## Go back to Koha
# Replace "<enter openid configuration endpoint>" with copied data from previous step
# Click "Add default OIDC mapping"
# At "Domain", type "*"
# Change "Allow OPAC" to "Yes"
# Change "Allow staff" to "Yes"
# Change "Auto register" to "Yes"
# Change "Update on login" to "Yes"
# Click "Submit"
# Restart your Koha
## e.g. koha-plack --restart kohadev
# Update http://localhost:8081/cgi-bin/koha/admin/preferences.pl?op=search&searchfield=OPACBaseURL to "http://localhost:8080"
# Update http://localhost:8081/cgi-bin/koha/admin/preferences.pl?op=search&searchfield=staffClientBaseURL to "http://localhost:8081"
=== SAML ===
# See Shibboleth Configuration and Shibboleth2.xml although the former appears to be out of date
## apt-get update
## apt-get install shibboleth-sp-common libapache2-mod-shib
## cd /etc/shibboleth
## shib-keygen -f
## cp shibboleth2.xml shibboleth2.xml.bak
## Go to "test" realm in Keycloak (e.g. http://sso:8082/auth/admin/master/console/#/test)
### On the left side, click "Realm settings"
### Click "SAML 2.0 Identity Provider Metadata"
### Copy this URL
## wget http://sso:8082/auth/realms/test/protocol/saml/descriptor
## mv descriptor keycloak.xml
## vim shibboleth2.xml
### Change "handlerSSL" from "true" to "false"
### Change "https://sp.example.org/shibboleth" to "http://localhost:8080/shibboleth"
### Change "https://idp.example.org/idp/shibboleth" to "http://sso:8082/auth/realms/test"
#### Remove "discoveryProtocol" and "discoveryURL"
### Add <MetadataProvider type="XML" validate="false" path="keycloak.xml"/>
#### NOTE: This will be around the commented out MetadataProvider examples
## vim attribute-map.xml
### Add the following:
###     <Attribute name="urn:oid:1.2.840.113549.1.9.1" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="email"/>     <Attribute name="urn:oid:2.5.4.4" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="surname"/>     <Attribute name="urn:oid:2.5.4.42" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>
## service shibd restart
## vim /etc/apache2/sites-enabled/kohadev.conf
### Under the OPAC VirtualHost, add the following:  
####  <Location "/">     AuthType shibboleth     Require shibboleth ShibUseEnvironment Off ShibUseHeaders On    </Location>
## service apache2 restart
## Go to http://localhost:8080/Shibboleth.sso/Metadata
## Go to "test" realm in Keycloak (e.g. http://sso:8082/auth/admin/master/console/#/test)
### On the left side, click "Clients"
### Click "Import client"
### Click "Browse" and choose the downloaded Metadata file from above
### Click "Save"
### Click "Client scopes"
### Click "http://localhost:8080/shibboleth-dedicated"
### Click "Add predefined mapper"
### Tick "X500 email", "X500 givenName", and "X500 surname"
### Click "Add"
## vim /etc/koha/sites/kohadev/koha-conf.xml
## Change "useshibboleth" from 0 to 1
## Add the following on the next line below "useshibboleth"
### <shibboleth>    <matchpoint>userid</matchpoint>    <mapping>      <userid is="email"></userid> <surname is="surname"></surname> <firstname is="givenName"></firstname>    </mapping> </shibboleth>
## echo 'flush_all' | nc -q 1 memcached 11211
## koha-plack --restart kohadev
# NOTE: Koha is hard-coded to use HTTPS for SAML, so you might need to adjust the URL manually to http://localhost:8080/Shibboleth.sso/Login?target=http://localhost:8080/cgi-bin/koha/opac-main.pl
## NOTE: In production, always use HTTPS. We're not using HTTPS here only because we're doing minimal functional local testing.