...
Parameter Name | Mandatory | Description | ||
Service Provider’s XML metadata | Yes | SAML metadata of the Circulation Manager's Service Provider in an XML format. MUST contain exactly one SPSSODescriptor tag with at least one AssertionConsumerService tag with Binding attribute set to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST. | ||
Service Provider’s private key | No | Private key used for encrypting and signing SAML requests. | ||
Identity Provider’s XML metadata | YesNo | SAML metadata of Identity Providers in an XML format. Used for non-federated IdPs that are not a part of any SAML federation. MAY contain multiple IDPSSODescriptor tags but each of them MUST contain at least one SingleSignOnService tag with Binding attribute set to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect. | ||
| List of Federated IdPs | No | List of federated IdPs. Currently, only the InCommon Federation is supported, but support for other federations can also be added in the future. | ||
Internal signing secret for OAuth and SAML bearer tokens | No | It's a sitewide configuration setting residing in on Sitewide Settings page and containing the secret used for signing Bearer tokens issued by SAML authentication provider and used by client applications to confirm their authentication status. | ||
| Session Lifetime | No | By default, Circulation Manager sets the CM's session length equal to the length of the IdP session, which is pretty short (usually from 30 to 60 minutes).
This may worsen the patron's user experience, forcing them to reauthenticate too often. For example, even the simplest tasks like showing the local shelf of checked-out books may require the patron to reauthenticate against their SAML institute after 30 - 60 minutes. Session Lifetime configuration setting was introduced to work around this issue, allowing to override the CM's session length and set it to an arbitrary number of days. In this case, until the CM's session expires, the patrons will have to reauthenticate only if they request SAML-protected resources. For example, patrons will be able to use their local shelves freely, but they will have to reauthenticate if they try to download a SAML-protected book. | ||
| Filter Expression | No | An optional filter expression that can be used to filter out patrons by their SAML attributes. Filter expressions are written using the Domain Specific Language (its grammar can be found here) resembling python. The filter expression only has access to a single variable context, an instance of SAMLSubject class that gives access to all SAML attributes. For example, if you want to authenticate using SAML only patrons having "eresources" as the value of their "eduPersonEntitlement" then you need to use the following expression: "urn:mace:nyu.edu:entl:lib:eresources" == subject.attribute_statement.attributes["eduPersonEntitlement"].values[0]
"urn:mace:nyu.edu:entl:lib:eresources" in subject.attribute_statement.attributes["eduPersonEntitlement"].values |
| Note |
|---|
Please note that Circulation Manager supports both non-federated and federated IdPs simultaneously, but there MUST be at least one IdP configured. |
Anchor create_sp_data create_sp_data
Generating the Required Service Provider Data
| create_sp_data | |
| create_sp_data |
...
Configure IdP SAML Metadata
Circulation Manager supports two different types of SAML IdPs:
- Independent IdPs that are not a part of any SAML federation. In this case, you can use the IdP metadata in an XML format.
- Federated IdPs. Currently, only the InCommon Federation is supported, but support for other federations can also be added in the future.
...
Configure Non-Federated (Independent) IdP SAML Metadata
- Copy the text of the XML document you received for the Identity Provider's service
- Paste the text into the Identity Provider's XML metadata field, as shown below
...
| Anchor | ||||
|---|---|---|---|---|
|
...
- Select desired IdPs from the dropdown, as it's shown in the picture below.
| Info |
|---|
If the dropdown list containing federated IdPs is empty, there might be an issue in saml_monitor cron. Please contact your administrator to resolve this issue. |
Final Steps
Configure Session Lifetime
- If desired for initial debugging, you can turn on Debug mode by entering the numeral 1 into the Service Provider's debug mode field.
- To assign a library to this integration, click the Libraries bar
- Click the drop-down menu for the Add Library field
- Select the library name for which the SAML integration will be used
- Review the configuration fields and click the Submit button to save the SAML integration
...