Common SSO Errors & Troubleshooting

Contents

Introduction

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

User Cannot Log In (Prompt to enter Betterworks-specific password)

When attempting to log into Betterworks, a user may be prompted to enter a Betterworks-specific password even though their organization is using the SSO integration.

To resolve:

  1. Ensure that the user has a Betterworks account
  2. Ensure that the user is not attempting to login from a bookmark
  3. Ensure that the user is typing their email address in lowercase letters, not caps (i.e. janey.public@betterworks.com vs. JANEY.PUBLIC@BETTERWORKS.COM)

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 when their organization is using the SSO integration:

  1. The user goes to https://app.betterworks.com (or https://eu.betterworks.com if their organization's Betterworks instance is on our EU datacenter)
  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 Identity Provider (IdP) such as Microsoft, Okta, etc.
  5. They enter their credentials
  6. The password is verified by the IdP 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 IdP 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 IdP'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 Organization 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