SSO set up steps for OpenAthens

To complete these steps you will need access to your OpenAthens administration area at the domain level and your StoryBox Hub Account Holder login details.

Set up steps

1. Log in to your OpenAthens admin portal.
2. Browse to Resources > Catalogue.
3. Choose the Custom tab then click Create.
4. Select the SAML option.
5. In a separate browser tab or window, log in to your StoryBox Account Settings as the Account Holder.
6. Scroll down to Other Account Actions on the right hand side and click Configure SSO details.
7. For Identity provider choose "OpenAthens".
8. Type some dummy text into the following fields, we'll come back to edit them properly later (we’re looking into changing how this works). For example:
   • IdP Entity ID or Issuer: tbc
   • SAML Login URL: https://storyboxhub.com
   • X.509 Certificate: tbc
   • User name attribute: tbc
9. Click the Update button at the bottom of the page.
10. This will generate a Metadata Download URL towards the bottom of the SSO settings page. Click it to open the metadata for OpenAthens in a new browser tab. Save it as an XML file.
11. Back in the OpenAthens admin portal, upload the XML file in the section where it asks for a metadata file.
12. Click the Create button.
13. Next, follow these steps in the OpenAthens documentation to find your OpenAthens metadata. Open your metadata address in a browser window.
14. Back in StoryBox Hub, you can now update the Configure Service Provider section as follows:
    • IdP Entity ID or Issuer: Copy the entityID URL from your metadata and paste it here. It might look something like this: https://idp.domain.com/openathens or https://idp.domain.com/entity
    • SAML Login URL: Copy the SingleSignOnService Location URL from your metadata and paste it here. It usually looks something like this: https://login.openathens.net/saml/2/sso/domain.com
    • X.509 Certificate: Copy the text that appears inside the X509Certificate tag from your metadata and paste it here, topping with -----BEGIN CERTIFICATE----- and tailing with -----END CERTIFICATE----- as per the example underneath the text box. 
15. The last part of the set up is attribute mapping. Please refer to the OpenAthens documentation about how to release attributes to third parties then populate the Attribute Mapping fields in StoryBox Hub:
    • User name attribute (required): This is not displayed anywhere but is used as a unique identifier for the sub-account that gets created during an SSO user's first log in. As such it is required, or individual sub-accounts cannot be created. Make sure this is released as a unique parameter. Usernames can be repeated in OpenAthens and are not unique, but giving the username a unique attribute name will avoid issues.
    • Email attribute (optional)
    • First name attribute (optional): If this is mapped it will appear in the top right corner when an SSO user is logged in, in the dropdown menu that takes them to their account settings. If it isn't mapped the organisation name will appear here instead.
    • Last name attribute (optional)
    • (Role and Group name attributes are optional and not currently utilised but may be used for personalised functionality in the future.)
16. Click the Update button. You should now be ready to test the connection.

Testing steps

1. Log out of your StoryBox Hub Account Holder settings.
2. While still on the StoryBox Hub homepage, click the LOG IN button in the top right corner.
3. Click SSO.
4. Find your Organisation Name in the dropdown box. (You can edit the name that shows here in your Account Holder settings.)
5. Click LOG IN.
6. Submit user credentials for your organisation.
7. You should be redirected back to StoryBox Hub and be logged in when the page loads. If you included a First Name attribute and it is mapped correctly, you will see the first name of the user you logged in as in the top right hand corner, otherwise you will see your organisation name.
8. Mouseover that name and choose "Account Settings". If you see a page similar to the below, it means the Username attribute is mapped correctly and your SSO set up is complete:
   If you see something else, such as a prompt for the Account Holder's password, it means there is an issue with the release/mapping of the Username attribute - please see the Troubleshooting section below.

Direct login page link and Level URL

If you can log in successfully, you can use this URL format as a direct link to your organisation's StoryBox Hub login page:

https://storyboxhub.com/login?sso_id=XXXX

Replace XXXX with the same number you see in your StoryBox Hub Entity ID and ACS URLs.

If you are adding StoryBox Hub to your Electronic Collections, use this URL in the Level URL field.

Troubleshooting

If you follow the steps above and experience any issues, please contact our support team with these details:

• Your identity provider's name
• Screenshots of your SAML configuration from your IdP’s admin portal
• Screenshots of any error messages
• A set of test user credentials