Single sign-on: Overview

The single sign-on (SSO) feature can be used to bridge user authentication between a partner website and ReadSoft Online, so users can access ReadSoft Online using credentials other than their ReadSoft Online credentials. This is beneficial because it lets you access multiple applications using a single log-in.

ReadSoft Online supports SSO using OpenID Connect and SAML. Of the two options, OpenID Connect is more modern and easier to configure.

OpenID Connect

OpenID Connect is an authentication protocol based on OAuth 2.0. It uses REST/JSON messages to authenticate users across websites and apps without having to own and manage password files. This means you can login to ReadSoft Online using Google account credentials, for example, or other identity providers that use OpenID Connect.

How it works

When you set up an identity provider in ReadSoft Online, the OpenID Connect metadata service must be publicly available. Currently, ReadSoft Online does not support internal OpenID Connect metadata endpoints. For added security, ReadSoft Online uses Hybrid Flow (response type: "code id_token"). ReadSoft Online also requires the OpenID Connect scopes, "openid" and "email".

When configuring the identity provider, you must specify an authorized redirect URI from ReadSoft Online. This is the address that users are redirected to after they have authenticated with the identity provider. When specifying the URI, use this format: https://host-name/sso/openidconnect

...where host-name is the Host name setting specified in the Company profile view.

If you set up an identity provider with Google, you only need to set up one OAuth 2.0 client ID for all your customer accounts.

ReadSoft Online maps the User name to the email address of the identity provider credentials. In other words, your ReadSoft Online user name must match the email that you use to login to the identity provider. When logging in via the identity provider, you must complete the login within 30 minutes from the time the login page is displayed.

After you configure your identity provider, you can enable single sign-on with OpenID Connect in ReadSoft Online.

Some identity providers allow deactivated account names to be recycled. This means, if you have an account at a third-party identity provider, and you delete it, someone else could register a new account with the same name and potentially use it to access ReadSoft Online. Therefore, it is important to always keep ReadSoft Online user accounts up to date, and never leave unused user accounts in the system.

SAML

To implement single sign-on authentication with SAML, you must configure an identity provider on the partner system. After that, you can enable single sign-on in ReadSoft Online.

The partner system requires:

  • an identity provider that can make encrypted SAML 2.0 requests.
  • an SSL certificate on the partner system that verifies the identity of the partner system.
  • an SSL certificate that contains a public key from the partner system.
  • the ReadSoft Online API key of the partner.

How it works


Single sign-on

Sending a SAML SSO request to ReadSoft Online

ReadSoft Online uses SAML 2.0 to implement single sign-on using POST binding. ReadSoft Online acts as the consumer of claims and the authentication is identity-provider initiated; it is not service-provider initiated.

To send an SSO request to ReadSoft Online, the identity provider must post a SAML token (example) to the ReadSoft Online Assertion Consumer Service URL using this format:

https://services.readsoftonline.com/SSO/SAML2/Consume?x-rs-key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Note that x-rs-key specifies the ReadSoft Online API key of the partner, and you must use the URL that corresponds to your region:

  • Europe: https://services.readsoftonline.com/
  • Australia: https://services-au.readsoftonline.com/
  • US: https://services-us.readsoftonline.com/

All SAML responses from the identity provider must be signed. However, signed SAML assertions are optional. ReadSoft Online accepts encrypted and unencrypted signed SAML assertions. If you choose to encrypt signed SAML assertions, you must use the public key in this ZIP file: https://production.readsoftonline.com/install/readsoftonline-saml.zip

Note: ReadSoft Online does not support SAML Metadata.

After you configure your identity provider, you can enable single sign-on with SAML in ReadSoft Online.

Troubleshooting

If you have problems logging in after you set up SSO for OpenID Connect or SAML, sometimes a track ID is displayed in your web browser. For your security, no other information is displayed about the issue. If you log in as a partner administrator, however, you can search for the track ID in the MESSAGE column of the Audit trail view to see why the login failed.