Testing SSO

From Koha Wiki
Jump to navigation Jump to search

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

  1. Go to http://sso:8082/auth/admin
  2. Login using the credentials from docker-compose.sso.yml

Create Realm

  1. In the top left corner, click "master", then click "Create Realm"
  2. Type "test" into "Realm name" then click "Create"
  3. On the left side, click "Realm settings"
  4. Click the links for "OpenID Endpoint Configuration" and "SAML 2.0 Identity Provider Metadata"

Create User

  1. On the left side, click "Users"
  2. Click "Create new user"
  3. At "Username" type "kohadev"
  4. At "Email", type "kohadev@koha-community.org"
  5. At "First name", type "Koha"
  6. At "Last name", type "Dev"
  7. Click "Create"
  8. Click "Credentials"
  9. Click "Set password"
  10. Choose a password for your user and fill in "Password" and "Password confirmation"
  11. Change the "Temporary" slider from "On" to "Off"
  12. Click "Save"
  13. Click "Save password"

Create client: OpenID Connect

  1. On the left side, click "Clients"
  2. Click "Create client"
  3. At "Client ID", type "kohaoidc"
  4. Click "Next"
  5. Change the "Client authentication" slider from "Off" to "On"
  6. Click "Next"
  7. Scroll down to "Valid redirect URIs"
  8. Add relevant URIs
    1. e.g. http://localhost:8080/*
    2. e.g. http://localhost:8081/*
  9. Click "Save"

Create client: SAML

  1. N/A (this is handled later in the process)

Extra Notes

  1. 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

  1. Go to http://localhost:8081/
  2. Log into the Koha staff interface
  3. Go to http://localhost:8081/cgi-bin/koha/admin/identity_providers.pl
  4. Click "New identity provider"
  5. At "Code", type "test"
  6. At "Description", type "Test"
  7. At "Protocol", choose "OIDC"
  8. Click "Add default OIDC configuration"
  9. Replace "<enter client id>" with "kohaoidc"
  10. Go to Keycloak
    1. On the left side, click "Clients"
    2. Choose "kohaoidc"
    3. Click "Credentials"
    4. Click the "eyeball icon" next to "Client secret"
    5. Copy the unmasked data and go back to Koha
  11. Replace "<enter client secret>" with copied data from previous step
  12. Go to Keycloak
    1. On the left side, click "Realm settings"
    2. Click "OpenID Endpoint Configuration"
    3. Copy this URL (e.g. http://sso:8082/auth/realms/test/.well-known/openid-configuration)
    4. Go back to Koha
  13. Replace "<enter openid configuration endpoint>" with copied data from previous step
  14. Click "Add default OIDC mapping"
  15. At "Domain", type "*"
  16. Change "Allow OPAC" to "Yes"
  17. Change "Allow staff" to "Yes"
  18. Change "Auto register" to "Yes"
  19. Change "Update on login" to "Yes"
  20. Click "Submit"
  21. Restart your Koha
    1. e.g. koha-plack --restart kohadev
  22. Update http://localhost:8081/cgi-bin/koha/admin/preferences.pl?op=search&searchfield=OPACBaseURL to "http://localhost:8080"
  23. Update http://localhost:8081/cgi-bin/koha/admin/preferences.pl?op=search&searchfield=staffClientBaseURL to "http://localhost:8081"

SAML

  1. See Shibboleth Configuration and Shibboleth2.xml although the former appears to be out of date
    1. apt-get update
    2. apt-get install shibboleth-sp-common libapache2-mod-shib
    3. cd /etc/shibboleth
    4. shib-keygen -f
    5. cp shibboleth2.xml shibboleth2.xml.bak
    6. Go to "test" realm in Keycloak (e.g. http://sso:8082/auth/admin/master/console/#/test)
      1. On the left side, click "Realm settings"
      2. Click "SAML 2.0 Identity Provider Metadata"
      3. Copy this URL
    7. wget http://sso:8082/auth/realms/test/protocol/saml/descriptor
    8. mv descriptor keycloak.xml
    9. vim shibboleth2.xml
      1. Change "handlerSSL" from "true" to "false"
      2. Change "https://sp.example.org/shibboleth" to "http://localhost:8080/shibboleth"
      3. Change "https://idp.example.org/idp/shibboleth" to "http://sso:8082/auth/realms/test"
        1. Remove "discoveryProtocol" and "discoveryURL"
      4. Add <MetadataProvider type="XML" validate="false" path="keycloak.xml"/>
        1. NOTE: This will be around the commented out MetadataProvider examples
    10. vim attribute-map.xml
      1. Add the following:
      2.     <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"/>
    11. service shibd restart
    12. vim /etc/apache2/sites-enabled/kohadev.conf
      1. Under the OPAC VirtualHost, add the following: 
        1.  <Location />     AuthType shibboleth     Require shibboleth ShibUseEnvironment Off ShibUseHeaders On    </Location>
    13. service apache2 restart
    14. Go to http://localhost:8080/Shibboleth.sso/Metadata
    15. Go to "test" realm in Keycloak (e.g. http://sso:8082/auth/admin/master/console/#/test)
      1. On the left side, click "Clients"
      2. Click "Import client"
      3. Click "Browse" and choose the downloaded Metadata file from above
      4. Click "Save"
      5. Click "Client scopes"
      6. Click "http://localhost:8080/shibboleth-dedicated"
      7. Click "Add predefined mapper"
      8. Tick "X500 email", "X500 givenName", and "X500 surname"
      9. Click "Add"
    16. vim /etc/koha/sites/kohadev/koha-conf.xml
    17. Change "useshibboleth" from 0 to 1
    18. Add the following on the next line below "useshibboleth"
      1. <shibboleth>    <matchpoint>userid</matchpoint>    <mapping>      <userid is="email"></userid> <surname is="surname"></surname> <firstname is="givenName"></firstname>    </mapping> </shibboleth>
    19. echo 'flush_all' | nc -q 1 memcached 11211
    20. koha-plack --restart kohadev
  2. 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
    1. NOTE: In production, always use HTTPS. We're not using HTTPS here only because we're doing minimal functional local testing.

 

Retrieved from "https://wiki.koha-community.org/w/index.php?title=Testing_SSO&oldid=32668"