Skip to main content

Single sign-on (SSO) implementation

Updated
Disclaimer: This feature is only available to certain customers at this time. Only contact SHOEBOX Support if this feature was offered as a part of your onboarding.

SHOEBOX SSO is compatible with third-party identity federation systems that adhere to the SAML 2.0 standard. For example:

  • Microsoft Active Directory Federation Services
  • Azure AD
  • Okta

Currently, SHOEBOX only supports Service Provider Initiated (SP-initiated) Single Sign-On (SSO) workflows. In this flow, users initiate the sign-in on our platform, which then redirects to the SAML Identity Provider (IdP) for authentication. Upon successful authentication, the IdP sends a SAML response back to our platform, allowing users to access our services. This ensures a seamless and secure login experience. For more information, refer to the AWS Documentation on SAML Authentication.

Note: This feature is optional, and is only available for customers with an existing identity provider (IdP). If your organization does not use SSO and does not have an IdP, you will continue to use the traditional login system to access your portal and PureTest app.

In this article:

How do I enable SSO for my organization?

Before you begin: Please note that enabling SSO is an administrative action. Only users configured as administrators will be able to initiate this process.

Step 1: Uploading IdP XML configuration file

Once the support team has enabled SSO for your organization, a new Single Sign-On (SSO) tab will appear in your portal's settings under the Administration heading. Clicking this will take you to the Single Sign-On (SSO) admin page.

A screenshot of the sidebar menu with the administration section highlighted.

Once on the Single Sign-On (SSO) page, you will notice the Single Sign On (SSO) Setup section. This is where you will go to upload your organization's SSO identity provider SAML2.0 configuration file in XML format.

Important: If you do not know what this is, you may need to work alongside a technical contact from an IT or development team who can put together the required XML file you will need to upload. Just let your technical contact know that you need a SAML2.0 configuration file, and that the only supported file format for upload is XML.
A screenshot of the SSO settings in the Data Management Portal.

Once your XML file has been uploaded, the SHOEBOX development team will start working on enabling SSO for your organization.

Note: At this point, you may be contacted and asked to help test if your SSO is working once it has been configured by the development team. This can be done using any account from your organization, admin or otherwise. If you provided the email addresses of users to test authentication back in Step 1, this will come into effect here.
Important: Once your SSO has been set up, you must notify the SHOEBOX support team if you plan on changing your IdP. Your configurations will need to be updated for your new IdP.

Step 2: Enabling SSO per user

Once SSO has been enabled, it is the admin user's responsibility to enable SSO for each user in their organization. SSO can be enabled for existing users, as well as every new user you create going forward.

Note: Users can only be native (username/password) or SSO users, not both.

To do this, access the Users page under the Administration heading in your portal's settings.

A screenshot of the sidebar menu with the Users option highlighted.

After selecting a user, notice at the bottom of their user information panel that Single Sign-On is set to Off by default. Additionally, the Reset Password button is still available, because at this point the user is still using their SHOEBOX email and password for login credentials.

A screenshot of a user profile with SSO deactivated.

Clicking the Pencil icon pencil-icon.png will allow you to enable SSO for the user by clicking the checkbox as seen in the image below.

Note: Once you click Save, the user's SHOEBOX credentials will no longer function. The user will need to use their SSO credentials to access the portal and SHOEBOX applications.
A screenshot of a user profile with SSO activated.

After clicking the checkbox and clicking on Save to save your changes, SSO will now be enabled for the user.

Known issues

Currently, the Reset Password button does not disappear after enabling SSO. This will be fixed in a future release. Clicking on the button after SSO has been enabled will not send a password reset email, at this point all credentials for the user are managed through the SSO provider.

A screenshot showing the known issue of the Reset Password button continues to be displayed even though SSO is enabled.

Testing SSO implementation

Once you have SSO Enabled, we recommend going through the minimum testing procedures indicated below:

Scenario 1: PureTest login

  1. Log in with an SSO user to PureTest.
  2. Go through the onboarding.
  3. Go to the settings and download the latest device settings.
  4. Log out and log in again with a different SSO user.

Scenario 2: Data Management Portal login

  1. Log into the web portal with an SSO user (email address). The portal will automatically redirect users to their Identity Provider (IdP) to enter their SSO credentials. They will be redirected back to the portal upon a successful login.
  2. Search for a patient or view participant data.
  3. Log out.
    • Note: Logging out from an SSO session is different. If you keep your browser open and enter your credentials on the login page while still logged in to your IdP, you will automatically be logged into the portal. For security reasons, we recommend that you close your browser (not just the tab) when logging out from a public computer.

Scenario 3: Extended SSO test procedures (PureTest + portal sanity checks)

  1. Log in with an SSO user to PureTest.
  2. Finish onboarding if necessary.
  3. Go to the settings and download the latest device settings.
  4. Complete test prep (depending on your configuration this may include headphones check, room scan and biological verification).
  5. Create a new patient.
  6. Complete a workflow for the new patient from start to finish.
  7. At the end of the test, everything should sync to the cloud. Visually confirm that the sync occurred.
  8. Log out from PureTest.
  9. Try to log in with another SSO user and log out again.
  10. Log to the portal with the first user and check patient data - patient should have questionnaire, audiogram and PDF file attached (depending on the workflow configuration).
  11. Delete the testing patient (if you don’t need it anymore).

Now that SSO is enabled, how do I log in to PureTest?

Once SSO has been enabled for a user, the next time they enter their email into PureTest to log in, the app will check to see if SSO is enabled. Once PureTest detects that the user has SSO enabled, it will open a new login window using your IdP's user interface. The user will enter their SSO credentials once here, and then the SSO process is complete.

An animated gif showing screenshots of a user logging in using SSO.

 

Related to

Related articles