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.

On your local machine

Set your hosts file

As the sso hostname doesn't often get passed back to the host, you'll need to edit your hosts file, and add an entry for it.

On macOS/Linux

  1. Open a terminal of your choice.
    • macOS systems can find the Terminal app in /Applications/Utilities
    • On GNOME, this can be found in Applications.
    • On KDE, find an application called Konsole.
  2. Using your favourite text editor (nano is a good choice, for beginners), edit the file with sudo
    • On macOS, this can be done with sudo nano /private/etc/hosts
    • On Linux, use sudo nano /etc/hosts
  3. Use your arrow keys to go to the bottom of the file, on a brand-new line, add the following:
    127.0.0.1    sso
  4. Save the file, by pressing CTRL + S, then exit nano with CTRL + X

On Windows

  1. Open the start menu, then type cmd.exe in the search box
  2. When Command Prompt shows up in the search results, right-click it, and pick 'Run as Administrator'
  3. In the terminal window that appears, type the following: notepad.exe C:\Windows\System32\Drivers\etc\hosts
  4. Scroll to the very bottom of the file, and on a brand-new line, add the following:
    127.0.0.1 sso
  5. Save the file, and close notepad


To reverse this process, you can just follow the steps backwards:

  • Remove the added line from the hosts file
  • Save and quit the text editor

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
      4. Change localhost:8082 to sso:8082 in the 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:
        <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: 
        <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"
      <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=38748"