Setting Up SSO for Lean Library Workspace

This article outlines the process for setting up SSO and details the information that Technology from Sage need from your IT team in order to complete the configuration. 

This article applies only to Lean Library Workspace. Other TfS products use slightly different SAML setup processes. 

The article is technical in nature and is intended to be read by the people in your IT team who manage your SSO Authentication configuration.

We've tried to write this in a way that will apply to all possible identity and authentication management systems that may be in use.

Process

Read this article in full. It sets out the process and includes details of the info we need in order to set up the configuration.

Each step listed here is detailed in it's own heading, with further explanation.

• Step 1: Raise a ticket. You will need some info from us!
• Step 2: Create your application. You will need to generate an application in your Identity Provider (IDP).
• Step 3: Plan attribute release. You will need to release some attributes to us to fill out the user's profile.
• Step 4: Share your info. This can't happen until steps 1, 2 and 3 have been completed. We will need to configure our authentication system to recognise your IDP.
• Step 5: Testing!

Step 1: Raise a ticket!

We want to be able to make sure you have clear communication and that we can guide you through this process as there are some specific things you will need to know at various stages.

Once you have raised a ticket we will tell you what your tenant name is so that you can use it in the later steps.

Please make sure a member of your IT Authentication team is included in the email conversation about this.

You can email support@leanlibrary.com and CC each person that needs to be involved. We'll include them all in the rest of the conversation.

Please tell us if you are using OpenAthens, as we can configure that for you without you having to do the rest of these steps! You will need to tell us

• Your OpenAthens Organisation ID
• Your 'Scope' that is used in your scoped affiliation.
  • For example: student@myuni.ac.uk has a scope of myuni.ac.uk 

Step 2: Create your 'application'

In your Identity Provider, you will need to create an application or connector (exact wording varies between systems) that will use SAML 2.0 to talk to our authentication system.

We use Amazon Cognito, and this service does not provide federated metadata in the way that you might be used to, so you will need to setup the connection manually.

We are also unable to use metadata from a federation such as the UK Access Federation, InCommon, EduGAIN or similar.

You will need the following information. The TENANTNAME given in the urls below will vary and we will tell you what this is in Step 1 above.

urn:amazon:cognito:sp:eu-west-1_etW74mVNx

https://authentication.sciwheel.com/saml2/idpresponse

https://authentication.sciwheel.com/authorize?response_type=code&identity_provider=TENANTNAME&client_id=2ioti3jsh7og4kd48nalgkisq5&redirect_uri=https://workspace.leanlibrary.com/login/oauth2/code/cognito

identity_provider=TENANTNAME&client_id=2ioti3jsh7og4kd48nalgkisq5&redirect_uri=https://workspace.leanlibrary.com/login/oauth2/code/cognito&response_type=code&scope=email+openid+profile

https://authentication.sciwheel.com/saml2/logout

Step 3: Plan attribute release

Lean Library Workspace requires a stable and persistent identifier for a user, plus some other info. We have listed these below in the table. It is important to know that we need the full names of the attributes as they will appear in the SAML responses to our login requests. 

We can map to any attribute if you are releasing it. The ones given here are examples that you might already be releasing and might be familiar to you. Some come from the EduPerson specification, while others are from Microsoft Entra claims.

Important. We do not support encrypted attributes assertions. Cognito does not yet support encrypted attribute assertions and so we are unable to support them.

urn:oid:1.3.6.1.4.1.5923.1.1.1.10  (eduPersonTargetedID)
urn:oid:1.3.6.1.4.1.5923.1.1.1.6  (eduPersonPrincipleName)

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
mail
urn:oid:0.9.2342.19200300.100.1.3  (eduPersonMail)

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
givenName
urn:oid:2.5.4.42. (eduPersonGivenName)

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
sn
urn:oid:2.5.4.4. (eduPersonSn)

Step 4: Share info with us

We need a very specific set of info for our team to efficiently setup these configurations. The configuration changes are subject to change control processes and so if they are not right first time, this could mean delays to setting up your SSO configuration.

myuni.ac.uk
students.myuni.ac.uk
company.com
staff.company.com

Step 5: Testing

Typically, you will set this up on your live system, do the steps outlined above, and we will configure it  in our system. Once it is ready to test we will ask you to login with a test user. The test user may be yourself, or one that mimics the roles and permissions of a real user.

Here are a few pointers for a successful test.

• Make sure that your test user is included in any active directory groups that grant access to the connection you have setup.
• You may wish to create a test group in your active directory system so that only the test users can access it before you also release the connection to other larger groups of users.
• One of the most common things we see after a customer goes live are 403 Unauthorised messages where the user is not in a group that has permission to login with that connector.