1. Betterworks
  2. How-to
  3. Integrations

Common SSO Errors & Troubleshooting

Contents

Introduction

This article is intended for users whose organization has our Single Sign-On (SSO) integration enabled. For more information on the integration, see the following articles:

User Prompted to Enter Betterworks Password

Note: An Identity Provider (IdP) is a system that stores and verifies a user's identity (i.e. Microsoft, Okta, etc.).

When attempting to log into Betterworks, the user may be prompted to enter a Betterworks password even though their organization has SSO enabled. This means that the user doesn't have a Betterworks password and would instead be using credentials from their organization's IdP.

To resolve:

  1. Ensure that the user has an active Betterworks account
  2. Ensure that the user is typing their email address in all lowercase letters, not caps or camelcase (i.e. use jane.doe@acmecorp.com rather than Jane.Doe@AcmeCorp.com or JANE.DOE@ACMECORP.COM)

Invalid Domain or SAML Token - Email Alias

saml_params.png

This may be the result of an email alias or a different primary email address. The following occurs each time a user whose organization has SSO enabled attempts to access Betterworks: 

  1. They go to app.betterworks.com
  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 an Identity Provider (i.e. Microsoft, Google, Okta, etc.)
  5. They enter their credentials
  6. The password is verified by the Identity Provider while the email address is sent to Betterworks for authentication
    • If the email address sent to Betterworks matches what we have on file for that 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 or a different primary email address. This means that the user may enter a particular email address, but the Identity Provider sends Betterworks another one. For example, Jane Doe may enter jane.doe@acmecorp.com, but Betterworks is sent j.doe@acmecorp.com. Since that isn't the email address that Betterworks has on file for Jane, the authentication will fail and Jane will be denied access.

To resolve:

A member of your IT Team can access the Identity Provider's administrative settings and update the user's email alias or primary email address to match what Betterworks has on file. You can find the email address that Betterworks has on file by going to the user's profile:

user_profile.png

Invalid Domain or SAML Token - IdP App Menus

Is the user accessing Betterworks from their IdP (i.e. Microsoft, Okta, etc.) apps menu?

To resolve:

Try having the user log into Betterworks directly from app.betterworks.com (or eu.betterworks.com if their organization is using the EU data center). 

Invalid Domain or SAML Token - Stale Sessions

Did the user bookmark their IdP (i.e. Microsoft, Okta, etc.) login page? This should be avoided because the URL is specific to that session and will not work for future sessions.

To resolve:

Try having the user log into Betterworks directly from the app.betterworks.com login page (or the eu.betterworks.com login page if their organization is using the EU data center). The user can bookmark either of these pages instead.

AADSTS50105 Error

AADSTS50105_error_message.png

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

This may be the result of an SSO certificate that 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 the 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