SAML-based authentication for patrons

The Circulation Manager occupies the Service Provider (SP) role in the SAML Protocol and authenticates a patron against an Identity Provider (IdP).

SAML-based authentication workflow for patrons is depicted on the picture below:

Image I. SAML Authentication Workflow in Circulation Manager
(content provider does not use SAML)

Both the Circulation Manager and IdP should have their metadata registered with each other. In the simplest case it can be a Shibboleth environment where SP’s metadata is added to IdP’s configuration and vice versa. However, the better solution would be to register the Circulation Manager in InCommon Federation which would allow to use of any IdPs in the federation.

The picture below shows how the workflow looks like in the case when the content is protected by a SAML authentication mechanism: either via SAML proxy or EZProxy with SAML authentication turned on.

Image II. SAML Authentication Workflow in Circulation Manager
(content provider uses a SAML proxy or EZProxy with turned on SAML authentication)

An alternate configuration may include a Authentication delegated to another application such as a CAS Server.

Image III. SAML Authentication Workflow in Circulation Manager
(content provider uses a SAML proxy or EZProxy with turned on SAML authentication and CAS Authentication Delegation)

In this case there are two authentication events:

1. User authenticates to the Circulation Manager. It works in exactly the same way as in the previous case: users will have to authenticate themselves against IdP either by entering credentials on the IdP’s form or using other mechanisms setup in the IdP’s settings.
2. User authenticates to SAML proxy/EZProxy. This should not require users to authenticate themselves against IdP. However, they may be shown a consent screen asking them to confirm using their credentials with a different SP (either SAML proxy or EZProxy).

Configuration

SAML-based authentication for patrons requires certain configuration to be set up to work correctly. Configuration parameters are described in the table I.

Table I. Circulation Manager SP’s Configuration

Setting up a SAML authentication provider in Circulation Manager

To set up a new SAML authentication provider in Circulation Manager you need to create a new authentication provider and set its type to SAML 2.0 Web SSO. After that you need to fill in mandatory parameters described above and show on the picture below:

• Name 
• Service Provider’s XML Metadata
• Identity Provider’s XML Metadata

If you want SAML assertions to be encrypted you need to set up an SP’s private key in Optional Fields group:

After you filled in all the parameters, you can link this provider to a library using Libraries group and then click on Submit to finish.

Testing

SAML testbed can be used for testing SAML authentication in Circulation Manager.

Using the testbed in client applications

• Fetch the authentication document: 

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

• Show available IdPs to the patron using a table, dropdown or different UI controls:
• 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

• 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

• After successful authentication the patron’s browser will be redirected to the URL specified in REDIRECT_URI with the following additional parameters:
• access_token containing a Bearer token
• 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

• Save access_token locally and use it every time while calling Circulation Manager API by passing it in the Authorization header.

• 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

• 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:
• The patron’s browser will be redirected to the OPDS URL.
• The OPDS SP will redirect the patron’s browser to the IdP
• The IdP will use the active authentication session and will return a SAML assertion to the OPDS SP
• OPDS SP will ask the patron to confirm that they agree to federate their credentials with OPDS by showing the consent screen:

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