Single sign-on

Single sign-on lets patrons sign in with the account they already have at your library or campus, through your identity provider (SAML 2.0). Two things come with it:

• Login details for patrons. Some databases come with a shared username and password, or special instructions. Add them to the database under Access & links → Login details. Signed-in patrons see them on the database's page; nobody else does, and they never appear in the public list, the API, the widget, the print view, or exports.
• Staff sign-in. Staff can sign in to the admin with the same account, so your identity provider's password rules and MFA apply.

Single sign-on is on the Plus plan and every trial. Only the library's owner can set it up or change it, because whoever controls it could sign in as any linked staff account. Admins can see the settings.

1. Register us with your identity provider

Open Settings → Single sign-on and choose Set up single sign-on. You get:

• an entity ID (also called the identifier or audience),
• a reply URL (the assertion consumer service, HTTP-POST),
• our metadata, which contains both plus our certificate.

Give these to whoever runs your identity provider. Where possible, ask them to:

• send a persistent name ID, or one of subject-id, eduPersonPrincipalName, or (Entra ID) the object ID, so the same person is always recognised;
• release mail and displayName, and on campuses eduPersonScopedAffiliation if you want to limit who counts as a patron;
• sign responses or assertions with SHA-256. Encrypting assertions to our certificate is supported and recommended.

Notes for common identity providers:

• Microsoft Entra ID: create an Enterprise application (non-gallery), choose SAML, upload our metadata, and copy the App Federation Metadata Url back to us. Assign the users or groups who should be able to sign in.
• Google Workspace: add a custom SAML app with our entity ID and reply URL, set the name ID to the primary email, then download Google's metadata and paste it here.
• Okta: create a SAML 2.0 app integration with our reply URL as the Single sign-on URL and our entity ID as the Audience URI, then copy its metadata URL.
• Shibboleth and InCommon: load our metadata into your IdP (or your federation registry) and release the attributes above. Paste your IdP's own metadata URL here, not the whole federation's; if you use federation metadata, also enter your IdP's entity ID.
• OpenAthens: register us as a SAML resource with our metadata, then use OpenAthens' metadata for your organisation.

Sign-in always starts from our side, so portal tiles (My Apps, the Okta dashboard) should link to your public list rather than send an unrequested sign-in.

2. Tell us about your identity provider

Under Tell us about your identity provider, give us its metadata URL (best, because we check it daily and pick up new certificates automatically), paste its metadata, or enter the entity ID, sign-in URL, and certificate by hand.

3. Test sign-in

Choose Test sign-in and sign in with your own account. Nothing is switched on. Afterwards the page shows whether it worked, who you signed in as, and every attribute your identity provider sent. If something went wrong, the reason is shown there too, for example an entity ID that does not match.

4. Who signs in

Automatic finds the unique ID, email, and name for most identity providers. After a test sign-in you can pick exact attributes instead. The unique ID must never be reused for another person, because staff accounts are linked to it.

Campus identity providers often sign in alumni, retirees, and guests as well. To limit login details to the people your licenses cover, turn on Only some people see login details and tick who counts: students, faculty, staff, employees, members, affiliates, alumni, or walk-in users. Add any other values your identity provider uses, such as retiree or guest. By default we read eduPersonAffiliation and eduPersonScopedAffiliation; you can choose another attribute, such as a group or role claim, instead.

5. Turn it on

• Patrons can sign in to see login details adds a Sign in to see login details button to databases that have login details. Patrons return to the same page, signed in, and can sign out from the bar at the top.
• Staff can sign in with single sign-on shows a Sign in with single sign-on option on the log-in page. Your staff sign-in link is shown once this is on.

Both need a test sign-in that worked first.

Staff accounts

Single sign-on never matches staff by email: an identity provider could claim any address. A staff account is linked in one of two ways:

• The staff member links it. They sign in with their password, open Settings → Profile, and choose Link my library sign-in.
• An admin gives access. The person signs in once with Sign in with single sign-on (they are told they do not have access yet). An admin then finds them under Staff users → Give access to someone who signed in with single sign-on and picks a role. The new account counts toward your plan's staff limit.

Signing in with single sign-on skips our own two-factor step, since your identity provider handles that. RefBytes administrator accounts always sign in with a password. Staff created through single sign-on have no password of their own; if they need one, they can use Forgot your password?.

Privacy

For patrons who sign in we keep their name, email, the ID their identity provider sends, and when they last signed in. Nothing records which databases they use. Patrons who have not signed in for a year are forgotten, and removing single sign-on forgets everyone at once. Your public privacy page explains this while patron sign-in is on.

Troubleshooting

• "The assertion is meant for …": the entity ID (audience) at your identity provider does not match ours. Copy it again from step 1.
• "The signature … does not match": your identity provider is signing with a certificate we do not have. Use a metadata URL so new certificates are picked up, or save its current metadata again.
• "… signed with … rsa-sha1": switch the identity provider to SHA-256.
• "A response arrived for a sign-in we did not start": the sign-in took more than ten minutes, or started from the identity provider's portal. Start from the library's page instead.