circulation-saml-test

Testbed which could be used for testing SAML-based patron authentication in Circulation Manager.

Architecture

Project consists of the following modules:

• metadata is a throwaway Dockerized busybox generating SAML metadata using confd
• ldap is a Dockerized version of 389 Directory Server based on 389ds GitHub project. Contains predefined test users described in init-users.ldif.tmpl and used by Shibboleth IdP as an authentication provider
• shibboleth-idp is a Dockerized version of Shibboleth IdP based on shibboleth-idp-dockerized and dockerized-idp-testbed GitHub projects
• flask-sp is a Dockerized Python SP based using OneLogin's python-saml library. Used for serving OPDS feeds
• elasticsearch is a Dockerized version of Elasticsearch with pre-installed analysis-icu plugin required by Circulation Manager
• circulation-test is a Dockerized Flask application used for testing SAML authentication in Circulation Manager
• proxy is a Dockerized nginx reversed proxy based on docker-nginx-with-confd GitHub project

The architecture of the testbed is shown in the picture below:

• cm-test.hilbertteam.net is a circulation-test instance used for authenticating and downloading books using Circulation Manager (cm.hilbertteam.net)
• cm.hilbertteam.net is a Circulation Manager instance with a SAML authentication provider acting as a SAML Service Provider (SP)
• idp.hilbertteam.net is a shibboleth-idp instance acting as a SAML Identity Provider (IdP)
• opds.hilbertteam.net and opds.hilbert.team are two instances of flask-sp serving two different OPDS feeds using SAML

Usage

---

For circulation manager developers

In case this environment is being used to test out SAML authentication integration with an already running CM on a development machine docker-compose-saml-test.yml can be used instead This file does not contain the db,es,cm and cm-test services.

---

Preparing the local environment

1. Update host names in .env file
2. Replace all the host names with 127.0.0.1 in etc/hosts file:

127.0.0.1     idp.hilbertteam.net
127.0.0.1     opds.hilbertteam.net
127.0.0.1     opds.hilbert.team
127.0.0.1     cm.hilbertteam.net
127.0.0.1     cm-test.hilbertteam.net

3. Build containers:

docker-compose build

4. Run metadata service to generate SAML metadata first (we need to run it first because it's used by other services):

docker-compose up -d metadata

NOTE: If the metadata service runs multiple times (over the course of development) it may overwrite the the output files In which case one would get an error while trying to authenticate

The application you have accessed is not registered for use with this service.

In this case please ensure the output cm.xml and idp.xml still match what has been set in the CM's Patron Authentication

5. Run all other services:

docker-compose up -d

Setting up Circulation Manager

Setting up a new administrator account

1. Open Circulation Manager and set up an administrator account:

2. Login into Circulation Manager:

Setting up a new library

3. Login into Circulation Manager:

4. Start setting up a new library by clicking on Create new library:

5. Fill in new library details:

6. Scroll down, click on Submit and wait until new library is created:

Setting up new collections

7. Click on Collections to start setting up collections:

8. Click on Create new collection:

9. Fill in details of a new collection using OPDS1_HOSTNAME as a URL:

10. Scroll down, associate the new collection with the library, click on Add library and then click on Submit:

11. Create a new collection using OPDS2_HOSTNAME as a URL:

Setting up a SAML authentication provider

12. Click on Patron authentication to start setting up a SAML authentication provider:

13. Click on Create new patron authentication service:

14. Fill in patron details using cm.xml to fill in SP details and idp.xml to fill in IdP details:

15. Scroll down, associate the library with the provider and click on Add library:

16. Click on Submit to finish creating a new authentication provider:

Setting up an Elasticsearch service

17. Click on Search to start setting up an Elasticsearch service:

18. Click on Create new search service:

19. Fill in details of an Elasticsearch service using es as a URL:

Importing the OPDS feeds

20. Connect to the Circulation Manager's Docker container:

docker-compose exec cm bash

21. Activate a Python virtual environment:

(env)> source env/bin/activate

22. Import the OPDS feeds:

(env)> bin/opds_import_monitor

23. Update the Elasticsearch indices:

(env)> bin/search_index_refresh

Testing SAML authentication

24. Open Circulation Manager test application and click on Authenticate to start authentication process:

25. Enter credentials from init-users.ldif.tmpl:

ℹ️ If you face an authentication issue, it might be because the LDAP server failed to import users. Please refer to Troubleshooting section for detailed instructions how to resolve this issue.

26. Click on Accept on the consent screen:

27. Borrow a book clicking on Borrow, wait until the operation is finished and then return back:

28. Download a book by clicking on Download:

29. Observe the downloaded book:

Troubleshooting

LDAP users don't get imported

Please note that sometimes LDAP server doesn't import correctly which results in authentication errors. To resolve this issue you will need to do the following:

docker-compose exec ldap bash

bash> ldapadd -x -D"cn=Directory Manager" -w${LDAP_MANAGER_PASSWORD} -f /init-users.ldif

Circulation Manager test applications errors out with error code 500

Sometimes during development and rebuilding/restarting of the containers you get error with the error code 500 when accessing Circulation Manager test application. Reason might be stale access token that gets rejected by the Circulation Manager. Solution is to delete the session cookie on the Circulation Manager test application and refresh the page.

Books don't show up

If you don't see any books in the admin UI or SimplyE, it might because the Elasticsearch server failed to import metadata because the cluster is in read-only state. To resolve the issue you need to do the following:

1. Update the Elasticsearch indices:

docker-compose exec es bash

bash> curl -XPUT -H "Content-Type: application/json" http://localhost:9200/_cluster/settings -d '{ "transient": { "cluster.routing.allocation.disk.threshold_enabled": false } }'
bash> curl -XPUT -H "Content-Type: application/json" http://localhost:9200/_all/_settings -d '{"index.blocks.read_only_allow_delete": null}'

bash> exit

2. Truncate work coverage records to be able to recreate the search index:

docker-compose exec db bash

psql -U simplified simplified_circulation_dev  # Please use the credentials from .env file
psql> truncate workcoveragerecords;
psql> exit;

bash> exit

3. Recreate the search index:

docker-compose exec cm bash

bash>  source env/bin/activate
(env)> bin/search_index_refresh
(env)> exit

4. Clear the CM's cache:

docker-compose exec db bash

psql -U simplified simplified_circulation_dev  # Please use the credentials from .env file
psql> truncate cachedfeeds;
psql> exit;

bash> exit