Single Sign-On: Common Errors & Troubleshooting

Introduction

This article is intended for customers that have a working Single Sign-On (SSO) integration. For more information on the integration, see the following articles:

User Cannot Log In (Invalid domain or SAML token)

saml__params.png

This is likely the result of an email alias. To clarify, the following occurs each time a user attempts to access Betterworks through SSO:

  1. The user goes to app.betterworks.com
    • Or eu.betterworks.com if their organization's Betterworks instance is on our EU data center
  2. They enter their email address
  3. Click "Log In"
  4. Based on the domain at the end of their email address, the user is redirected to their organization’s SSO page
  5. They enter their credentials
  6. The password is verified in the SSO server while the email address is sent to Betterworks for authentication
    • If the email address sent to Betterworks matches what we have on file for the user, authentication is successful and the user gains access
    • If the email address doesn't match, authentication fails and the user is denied access

However, oftentimes a user has an email alias. This means that the user may enter a particular email address, but the SSO server sends Betterworks the alias. The alias may be a completely different email address.

To resolve:

A member of your organization’s IT Team will need to update the alias in the SSO server's administrative settings to match the email address that Betterworks has on file. To view the email address that Betterworks has on file for the user, simply go to their profile:

profile.png

User Cannot Log In (AADSTS50105)

AADSTS50105.jpeg

This error occurs when a user is not assigned to a role for the Betterworks application.

To resolve:

A member of your organization's IT team will need to assign the user access within Microsoft. This Microsoft article provides instructions for the process.

Entire Org Cannot Log In

If your entire organization is unable to access Betterworks, it is likely that the SSO certificate has expired.

To resolve:

A member of your organization's IT Team will need to regenerate the SSO metadata using the new certificate.

Note: Our platform does not store certificates as separate files. Rather, an organization's certificate information is part of their SSO metadata.

Once the updated metadata is available, simply send it to the Support Team — support@betterworks.com. When received, we will:

  1. Update the metadata on the backend
  2. Run a test
  3. Send you a confirmation