SAML Testbed

Testbed

The testbed is a simple test environment demonstrating how SAML-based authentication works. It contains the following components:

• SAML-guarded OPDS feeds:
• http://opds.hilbertteam.net/feed
• http://opds.hilbert.team/feed
• Circulation Manager with setup SAML-based patron authentication
• Shibboleth IdP used by the OPDS feed and the Circulation Manager instance
• Test Flask application using Circulation Manager to download books

OPDS feeds and Circulation Manager use a Shibboleth instance as an Identity Provider (IdP) and have their metadata set up with it.

Circulation Manager credentials:

• Login: admin@cm.hilbertteam.net
• Password: admin@cm.hilbertteam.net

Please note that this version of the Circulation Manager is not stable yet and most likely you will face some issue while trying to use it.

Usage (via the test Flask application)

1. Open http://cm-test.hilbertteam.net in your browser. You will be presented with a list of all available IdPs configured in the Circulation Manager:

1. Select one of the configured IdPs and click on Authenticate after which the Circulation Manager will start the authentication process.
   
2. During the authentication process the browser will be redirected to Shibboleth IdP authentication page where you need to enter the following credentials (they are hardcoded in the LDAP instance used by Shibboleth IdP):

• Username: student1
• Password: password

1. Confirm that your agree to share your details with Circulation Manager SP by clicking on Accept button:

1. After this you will be redirected back to the test Flask application where you will be presented with the following information:

• Authentication token is a Bearer token created by the Circulation Manager after successful authentication and which should be by the client application during all the communications with the Circulation Manager
• Patron info is a JSON document containing information about the authenticated patron (its content depends on the patron’s attributes sent by the IdP)
• Available books is a table containing a list of available books in the library

1. Select a book and click on Borrow. The test application will send a borrow request to the Circulation Manager and will show the response on the screen:

1. After successful borrowing of a book return back to the previous page and click on Download button.
2. After this Circulation Manager will return the raw link to SAML-guarded OPDS feed.
3. The OPDS feed application will see that you’re not yet authenticated with it and will redirect you to the Shibboleth IdP authentication page. However, using the same domain name for Circulation Manager SP and OPDS feed SP will allow Shibboleth IdP to use cookies to see that you were previously authenticated with it through Circulation Manager SP.
4. Shibboleth IdP will ask you to share your details with OPDS feed SP where you will need to click on Accept button:
   
5. After this you will get access to the book:

Using the testbed in client applications

1. Fetch the authentication document:

GET http://cm.hilbertteam.net/authentication_document

1. Show available IdPs to the patron using a table, dropdown or different UI controls:

1. After the patron selects a particular IdP, authenticate them with the Circulation Manager.
   In the browser open the authentication link of the selected IdP. It has the following format: http://cm.hilbertteam.net/SAML/saml_authenticate?redirect_uri=<REDIRECT_URI>&provider=<PROVIDER>&idp_entity_id=<IDP_ENTITY_ID>
   where

• REDIRECT_URI is a URL where CM will redirect the browser after successful authentication.
• PROVIDER is the name of the used authentication provider (currently, there is only one - SAML 2.0)
• IDP_ENTITY_ID is the entityID of the selected IdP

For example,
GET http://cm.hilbertteam.net/SAML/saml_authenticate?redirect_uri=http%3A%2F%2Fcm-test.hilbertteam.net%2Flogin&provider=SAML+2.0

1. During the authentication process the patron’s browser will be redirected to Shibboleth IdP authentication page where their will need to enter the following credentials (they are hardcoded in the LDAP instance used by Shibboleth IdP):

• Username: student1
• Password: password

1. After successful authentication the patron’s browser will be redirected to the URL specified in REDIRECT_URI with the following additional parameters:
1. access_token containing a Bearer token
2. patron_info containing a JSON document with patron’s metadata

For example,
GET
http://cm-test.hilbertteam.net/login?access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTQU1MIDIuMCIsInRva2VuIjoie1wibWFpbFwiOiBcInN0dWRlbnQxQGlkcHRlc3RiZWQuZWR1XCIsIFwiZmlyc3RfbmFtZVwiOiBcIlN0dWRcIiwgXCJsYXN0X25hbWVcIjogXCJFbnRcIiwgXCJ1aWRcIjogXCJzdHVkZW50MVwifSJ9.trmLC4JQDaeGK4d0O8sbOtHvk32KR6ksQZOTg_mD67U&patron_info=%7B%7D

1. Save access_token locally and use it every time while calling Circulation Manager API by passing it in the Authorization header.
2. For example, to download the book use the fulfill endpoint in the browser:
   GET
   http://cm.hilbertteam.net/BASIC/works/7/fulfill/2
   Authorization: Bearer: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTQU1MIDIuMCIsInRva2VuIjoie1wibWFpbFwiOiBcInN0dWRlbnQxQGlkcHRlc3RiZWQuZWR1XCIsIFwiZmlyc3RfbmFtZVwiOiBcIlN0dWRcIiwgXCJsYXN0X25hbWVcIjogXCJFbnRcIiwgXCJ1aWRcIjogXCJzdHVkZW50MVwifSJ9.trmLC4JQDaeGK4d0O8sbOtHvk32KR6ksQZOTg_mD67U
3. Please note that fulfill endpoint also has to be used in the browser because calling it will lead to repeating the SAML authentication workflow as it described above:
1. The patron’s browser will be redirected to the OPDS URL.
2. The OPDS SP will redirect the patron’s browser to the IdP
3. The IdP will use the active authentication session and will return a SAML assertion to the OPDS SP
4. OPDS SP will ask the patron to confirm that they agree to federate their credentials with OPDS by showing the consent screen:

1.  After the patron clicks on Accept their browser will be redirected to the book: