Common SSO Errors & Troubleshooting

Contents

• Introduction
• User Prompted to Enter Betterworks Password
• Invalid Domain or SAML Token
  • Email Alias
  • Outdated SAML Token
  • IDP Apps Menu
  • Stale Session
•  Microsoft AADSTS50105 Error
• Entire Organization Cannot Log In

Introduction

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

• SSO Overview
• Configuring SSO (SAML 2.0)
• Configuring SSO (Google OAuth 2.0)

User Prompted to Enter Betterworks Password

Note: An Identity Provider (IDP) is a system that stores and verifies a user's identity. Common IDPs are Okta, Microsoft ADFS, Microsoft Entra ID (formerly Microsoft Azure AD), and Google, but there are many more.

When attempting to log into Betterworks, the user may be prompted to enter a Betterworks password even though their organization has SSO enabled. Users whose organization have SSO enabled don't have Betterworks passwords. They use their IDP credentials to access Betterworks. 

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 [e-mail] rather than [e-mail] or [e-mail]).

Invalid Domain or SAML Token

Email Alias

Note: An Identity Provider (IDP) is a system that stores and verifies a user's identity. Common IDPs are Okta, Microsoft ADFS, Microsoft Entra ID (formerly Microsoft Azure AD), and Google, but there are many more.

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. Based on the domain at the end of their email address, the user is redirected to their organization's custom login page hosted by their IDP
2. They enter their credentials
3. 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 [e-mail], but Betterworks is sent [e-mail]. 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 IDP'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:

Outdated SAML Token

Note: An Identity Provider (IDP) is a system that stores and verifies a user's identity. Common IDPs are Okta, Microsoft ADFS, Microsoft Entra ID (formerly Microsoft Azure AD), and Google, but there are many more.

Is Microsoft Entra ID your IDP? It's likely that your organization is using an outdated SAML token. Due to recent upgrades, an outdated SAML token can cause periodic login issues for some users.

To resolve:

A member of your organization's IT team will need to update the SAML token. Please contact [e-mail] and a member of the Support Team will provide the new one. 

IDP Apps Menu

Note: An Identity Provider (IDP) is a system that stores and verifies a user's identity. Common IDPs are Okta, Microsoft ADFS, Microsoft Entra ID (formerly Microsoft Azure AD), and Google, but there are many more.

Is the user accessing Betterworks from their IDP's apps menu?

To resolve:

Try having the user log into Betterworks directly from app.betterworks.com (or eu.betterworks.com for organizations whose instance is on the EU data center). 

Stale Session

Note: An Identity Provider (IDP) is a system that stores and verifies a user's identity. Common IDPs are Okta, Microsoft ADFS, Microsoft Entra ID (formerly Microsoft Azure AD), and Google, but there are many more.

Did the user bookmark their IDP 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 eu.betterworks.com for organizations whose instance is on the EU data center). The user can bookmark either of these pages instead.

Microsoft AADSTS50105 Error

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 expired SSO certificate.

To resolve:

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

Note: We cannot incorporate a new certificate independently; it must be included in new SSO metadata. This is because our platform does not store certificates as separate files.

Once the updated metadata is available, simply send it to [e-mail]. When received, a member of Support Team:

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