1. Absorb Help Center
  2. Frequently Asked Questions (FAQs)
  3. SSO Troubleshooting

Troubleshooting Incoming SAML SSO

Updated

Introduction

This article contains information about common errors and messages that you may encounter when implementing Incoming SAML Single-Sign-On (SSO) with Absorb LMS.

Table of Contents

Common SSO Configuration Errors

Error Details

Key (X509
Certificate)

Make sure that there are no line breaks or spaces in the key when it is entered to Absorb; this should exactly match what is in the SAML Response.

Id Property

This must match what your identity provider is sending as the NameId value in the SAML Response to match to a user in the LMS using the Id Property as defined in your SSO configuration settings within Absorb.

Consumer Assertion/ACS URL

This URL should follow the format [https://company.myabsorb.com/api/rest/v2/authentication/saml]

Assigned Route

A route must be assigned to the SSO configuration in the LMS; otherwise, the SSO configuration will not activate.

Relay States

For Identity Provider Initiated configurations, if relay states are desired, this option must be enabled through your SSO provider, or they will be ignored upon successful authentication.

 

HTTP Code: 200

200: Multiple Users

HTTP Code: 200 - Multiple Users
Error

Absorb Dashboard Message: "We apologize; multiple users were found matching the NameID assertion."

Example: https://PortalURL.myabsorb.com/#/sso-error?ssoError=SamlMultipleUsersFound"
Explanation

When clicking the Absorb LMS app in the SSO portal, the user receives the above message.
Solution Remove or edit users that have the same unique identifier. In the above issue, there were users with the same email address under Inactive and Active users.

  

Error Example
200-multiple-users-error.png

 

200: Code after Successful Log In

HTTP Code: 200 - 200 after successful login
Error

The Login shows as Successful in the Logins table, and the learner is taken to one of the following error pages:

However, a grey screen is seen with three dots, and the page never loads.
Explanation

The Single Logout URL is invalid in the SSO Settings.
Solution

The Logout URL must begin with https://

 

200: Invalid or Not Found Credentials

HTTP Code: 200 -Invalid or not found credentials

Error

 

Absorb Dashboard Message: Invalid or not found credentials

Example: https://portal.myabsorb.com/#/sso-error?ssoError=CredentialsInvalidOrNotFound
Explanation The user attempting to log in is Inactive in the LMS.
Solution The user must be Active in the LMS for them to successfully log in.

 

HTTP Code: 302

302: No Matching User Found or There was an Error with Username

HTTP Code: 302 - No Matching User Found
Error

Absorb Login Screen "We apologize; no matching Absorb user was found, or there was an error with the username"

Example: https://Company.myabsorb.com/#/sso-error?ssoError=SamlNoUserFound
Explanation After Authenticating with the SSO provider, the User selects the App on the SSO portal and is routed to the Absorb dashboard with an error.
Solution If user provisioning is DISABLED (Error reads: We apologize; no matching Absorb user was found):
  • If the user doesn't exist in the LMS, create the account.
  • If the user already exists in the LMS, change the ID Property in the Absorb side configuration to match your Identify Providers in the Name ID Property of the SAML Response.

If user provisioning is ENABLED (Error reads: We apologize; there was an error with the username)


This error is generic and can mean any of the following:

  • The following required fields (Username, FirstName, LastName, Department, etc.) are used as the ID Property.
      • Example: The ID Property is not a username; however, the username requested is not available.
      • Example: The ID Property is an email address. There isn't a User with that ID Property, but there is a user with the exact email address as their Username.
      • Example: The ID Property is not the Username, and there are multiple matches for the ID Property.
      • Attributes are Case Sensitive; ensure that the claims are in the correct format. (ie INCORRECT = "nameid" will error, CORRECT = "NameID")
      • ExternalDepartmentID cannot contain special characters: . _@%$&
Explanation

There are multiple possible causes for this error:

A. The Key in the SAML response is encrypted, which is not supported. You will be able to verify this is the cause of the issue if <Encrypted Key> displays in the SAML response.

B. The x509 key in the request does not match what's in Absorb.

C. The SAML response is being re-used: Some clients have looked to re-use SAML Responses as part of their SSO process through custom SSO configurations. Unfortunately, this will not work as Absorb performs a one-time-use check.

D. The timing of the SAML response doesn't fall within the timeframe specified in the SAML response
Note: This error may also display as SAML Request Issue Instant too old to trust.
E. An attribute being passed for SSO Provisioning has a line/Carriage break in it.
Solution

A. Absorb Does not support Encrypted SAML Responses. In ADFS, Removing the entry under the encryption tab of the ADFS SSO properties for the Absorb connection and moving them to the Signature tab should help, as Absorb does support signed responses.

B. Update the signature key in Absorb so that it matches what is being sent in the request by the Identity provider.

  • Ensure that the Key field in your LMS SSO settings contains no spaces or other characters that do not match what is sent in the response.

C. Avoid SAML responses being re-used.

D. Ensure that the correct SAML responses are used and fall within the timeframe specified in the SAML response.

E. If Provisioning is to be enabled on the portal, ensure that entries being passed are on a single line of text, within the character limit for that field.
Explanation

This error happens when there is a mismatch between the Mode selected in the Absorb SSO Settings and the Login URL entered. If SP-initiated mode is selected, the Login URL should be the IDP endpoint for SAML requests. If IDP-initiated mode is selected, the Login URL should be the user access page.

Note: SP-initiated is the recommended setup for incoming SSO.
Solution If you are using the recommended Service Provider Initiated SSO: 
  • Ensure that the selected Mode is Service Provider Initiated
  • Ensure that the Login URL is set as the SAML endpoint for SP-initiated SSO requests. For example, in OneLogin the URL will be similar to: https://Company.onelogin.com/trust/saml2/httppost/sso/439976
If Identity Provider Initiated SSO must be used instead:
  • Ensure that the selected Mode is Identity Provider Initiated
  • Ensure that the Login URL field is populated with the user access URL for the LMS application within your identity provider.
    • Note: for Azure, this is the User Access URL, not Azure's Login URL. The correct URL looks similar to: https://myapps.microsoft.com/signin/Absorb%20LMS/[someid]

 

Error Example -Provisioning Disabled  Solution Example  - Provisioning Disabled 
Error-302-No-User-Found-Example.png Solution-302-Provision-Disabled.png

 

302: Response Signature could not be Verified

HTTP Code: 302 -  No Matching Absorb User Was Found (Response Signature Error)
Error

Absorb Login Screen "We apologize. The Single-Sign-On response signature could not be verified." 
Explanation

There are multiple possible causes for this error:

  • This message appears after entering credentials/authenticating on the remote site/system. You will be able to tell this error comes from others because, in SAML Tracer, you'll see it trying to send a <EncryptedKey> field.
  • Everything in the request looks correct; however, the x509 key in the request does not match what's in Absorb.
  • The SAML response is being re-used. Absorb performs a one-time-use check.
  • The timing of the SAML response doesn't fall within the timeframe specified in the SAML response.
Solution

Absorb Does not support Encrypted SAML Responses. Removing the entry under the encryption tab of the ADFS SSO properties for our connection and moving them to the Signature tab should help, as we support signed responses. 

  • Updating the signature key in Absorb so that it matches what is being sent in the request by the SSO.
  • Ensure that the Key field in your LMS SSO settings contains no spaces or other characters that do not match what is sent in the response.
  • Avoid SAML responses being re-used.
  • Ensure that the correct SAML responses are used and fall within the timeframe specified in the SAML response.

Correct

<saml:Conditions NotBefore="2021-06-09T22:19:54.650439+00:00" NotOnOrAfter="2021-06-09T22:20:24.650470+00:00"/><saml:AuthnStatement AuthnInstant="2021-06-09T22:19:54.650439+00:00">

 

Incorrect

<saml:Conditions NotBefore=\"2021-06-08T12:21:53.682Z\" NotOnOrAfter=\"2021-06-08T12:26:53.682Z\" />
<saml:AuthnStatement AuthnInstant=\"2021-06-08T19:21:53.682Z\">

 

Error Example
302-error-sig-not-verified.png

 

Solution Example 
302-Signature.png 302-Signature-ADFS MGMT.png

 

HTTP Code: 400

HTTP Code 400: "...not a valid SAML 2.0 protocol"

HTTP Code: 400 - Not a Valid SAML 2.0 Protocol
Error

The User receives an error advising SAML request is not valid/must be present.

"The request is not a valid SAML 2.0 protocol" OR "SAMLRequest or SAMLResponse must be present as query string parameters in the HTTP request for SAML Redirect binding" message.
Explanation

This error happens when the wrong login URL is applied in the SSO settings in Absorb on an IdP initiated SSO set up (e.g. with Microsoft Azure or ADFS). The login URL should not be a SAML request URL, just the URL of a page where someone can log in. If the client wants the SSO to know who the user is, then they need SP initiated.
Solution

If Service Provider Initiated mode is used: 

  • Change the Mode field in the LMS SSO settings to Service Provider Initiated.

If Identity Provider Initiated mode is used: 

  • Correct the Login URL field to the identity provider's access URL. For Azure, this is the User Access URL (not Azure's Login URL), the correct URL looks similar to: https://myapps.microsoft.com/signin/Absorb%20LMS/[someid]

 

Error Example
200-error-SAML-response.png

 

HTTP Code: 403

HTTP Code: 403
Error

Upon putting in the Username and Password for SSO Login, the following error occurs. 

  • Click on the Absorb App inside the SSO portal; the link is broken and goes to an error page.
  • "Validation 403 Sign-On Request not permitted Site can't be reached."
  • "Single Sign-On Requests are not permitted."

Alternate error language may present:
SAMLRequest or SAMLResponse must be present as query string parameters in an HTTP request for SAML Redirect binding.
Explanation

The route assigned to the SAML Consumer URL within the SSO provider did not match the URL assigned to "Assigned Route" in Absorb SSO Setup.
Solution Update the Consumer URL in the SSO Provider.

 

Note: Right-Click on the images to enlarge and open in a new browser window/tab.

Error Example Solution Example
error-403.png Solution Example.jpg

 

 SSO Deep Linking: IDP Relay State

SSO Deep Linking: IDP Relay State
Error

When using a deep link, the user is asked to authenticate through the client SSO login page and then transported to the dashboard, not the deep-linked area.
Explanation

IDP Mode does not retain the relay state when transporting a user through SSO.

Detailed instructions for Deeplinking
Solution 
 While Deep linking can be used with an IdP initiated SSO, it requires the use of a relay state set up by the client in order to retain the deep linked page when a user logs in through a deep link. As well Switching to using SP Initiated over IdP initiated would eliminate this need and is generally the recommended approach.

 

SAML SSO Support

Disclaimer: Absorb LMS supports SAML 2.0 Single Sign-On as a feature; however, we do not officially support any specific client-side (IdP) solution. Although many platforms generally work with our implementation of SAML SSO, it is the client's responsibility to configure/develop, and maintain their side of the integration. Your team will require a resource who is knowledgeable and familiar with your specific SSO instance.

Please include a SAML trace of your login attempt when submitting a support ticket for SSO-related issues to expedite resolution. 

 

SAML Trace: Google Chrome

A good option is the SAML Chrome Panel extension which appears in the Chrome Developer Tools once installed.

1. Press F12 to start the developer console.

2. Select the SAML tab.

3. Reproduce the issue.

4. Click the Export button to download the report: 

 

SAML Trace: Firefox

The Firefox add-on SAML Tracer can prove helpful.

1. Click on the SAML-tracer icon in your browser window:  

2. Reproduce the issue.

3. Look for an orange SAML label in the table to ensure the SAML transaction was captured.

4. Click Export:  

 

Provisioning Errors

If the SAML authentication is verified but the user does not exist in the LMS, provisioning will be attempted. However, issues provisioning the user will result in an error describing the user provisioning issue:

  • Notification that the there was an issue creating their account
  • Information on the attributes that resulted in a failure to provision the user (if applicable)

An error will occur and the user will not be provisioned if:

  • Mandatory user fields for an LMS profile are missing or invalid
    • Mandatory fields include username, first name, last name, and department.
    • Fields set as required in the portal's user profile and custom field settings can be overridden by an administrator as desired. As such, these fields are not treated as mandatory for account provisioning.
  • Attribute statement does not include the Id property used in the authentication stage
    • In addition to the mandatory fields listed above, the Id property used in the authentication stage is also mandatory. For example, if SSO attempts to authenticate using email address, an "Email" attribute must be present for the provisioned user to ensure that the next time they authenticate there is a value present to match on, otherwise provisioned accounts would be orphaned the next time the user attempts to authenticate.
  • The Id property's value in the attribute statement does not match the NameId's value in the authentication statement
    • Further to above, Absorb also requires that the value passed in the NameId (used in the authentication stage) matches the value included in the attribute for the Id property in the provisioning stage. For example, if SSO attempts to authenticate on email address, the "Email" attribute must contain the same value as the NameId value used for authentication, otherwise provisioned accounts would be orphaned the next time the user attempts to authenticate.
  • The username included in the attribute statement already exists in your Absorb portal
    • This error is only possible if the Id property set in your SSO config is NOT username (e.g. email, external Id, or Absorb Id); if that value does not exist in Absorb, a user provisioning attempt is made, but if the username specified for the new user already exists, another user with that username will not be created.
  • Attribute statement includes an attribute value that fails to meet the minimum restrictions imposed on the field(s)
    • Please see the Default Fields and Custom Fields sub-sections below for accepted attribute values
    • e.g. ProvinceCode is provided but CountryCode is not provided
    • e.g. ProvinceCode does not belong to the provided country
    • e.g. CountryCode or ProvinceCode are provided but do not match a supported country or province code or format. At the time of writing, Absorb LMS supports the majority of ISO 3166-2 alpha-2 province codes. In cases where a country's divisions directly overlap with a set of sub-divisions, Absorb has opted to support at a minimum the lowest-level sub-division for the region and may not support all official regional councils, administrative divisions, territorial collectivizes, etc. Please review existing LMS country/province dropdowns to view all supported countries and their respective sub-divisions.

Specific Error Messages

Error Message

 Potential Cause(s)

No matching Absorb user was found.
  • This could be related to the general SSO setup, not specifically provisioning. Make sure the SSO works for an existing user before doing any further troubleshooting.
  • Sometimes, is a generic error, similar to the We were unable to provision a user. error below.

We were unable to provision a user.
  • Generic Error, which is shown if none of the below errors apply.
We were unable to provision a user. There was a problem with 'Username'.
  • Username is not unique in the portal (this is often caused when an inactive user matches the Username of an existing user).
  • Username is selected as the Id Property, but doesn't match the SSO Name Id in the SAML Response.
  • Username not provided.
  • Username exceeds 255 characters.
  • The name of the attribute (Username) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'Email'.
  • Email doesn't follow proper email address syntax.
  • Email Address is selected as the Id Property in the portal's SSO config, but not provided in the provisioning request.
  • Email Address is selected as the Id Property, but doesn't match the SSO Name Id in the SAML Response.
  • Email exceeds 255 characters. The name of the attribute (Email) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'EmployeeNumber'.
  • Employee Number is selected as the Id Property in the portal's SSO config, but not provided in the provisioning request.
  • Employee Number is selected as the Id Property, but doesn't match the SSO Name Id in the SAML Response.
  • EmployeeNumber exceeds 255 characters.
  • The name of the attribute (EmployeeNumber) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'UserExternalId'.
  • External Id is selected as the Id Property in the portal's SSO config, but not provided in the provisioning request.
  • External Id is selected as the Id Property, but doesn't match the SSO Name Id in the SAML Response.
  • UserExternalId exceeds 255 characters.

We were unable to provision a user. There was a problem with 'Gender'.
  • Gender provided but is not 0, 1, or 2.
  • The name of the attribute (Gender) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'DateHired'.
  • DateHired provided but not in a proper ISO format.
  • The name of the attribute (DateHired) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'Department Id'.
  • Departmentid is not a valid GUID.
  • The name of the attribute (DepartmentId) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'ExternalDepartmentId'.
  • Department with the specified external id doesn't exist.
  • Portal has multiple departments with the provided External ID (must be exactly 1 or provisioning will fail).
  • Neither ExternalDepartmentId nor DepartmentId were provided.
  • ExternalDepartmentId exceeds 255 characters.
  • The name of the attribute (ExternalDepartmentId) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'CustomFields'.
  • Custom fields provided, but malformed. Absorb doesn't specify which custom field was the issue.
  • See the Custom Fields section for information on how to properly format custom fields.
  • The name of the attribute (String1, Decimal1, DateTime1, Bool1, etc) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'FirstName'.
  • FirstName not provided.
  • FirstName exceeds 255 characters.
  • The name of the firstName attribute within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'LastName'.
  • LastName not provided.
  • LastName exceeds 255 characters.
  • The name of the lastName attribute within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'Address'.
  • Address exceeds 4000 characters.
  • The name of the attribute (Address) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'Address2'.
  • Address2 exceeds 4000 characters.
  • The name of the attribute (Address2) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'City'.
  • City exceeds 255 characters.
  • The name of the attribute (City) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'CountryCode'.
  • CountryCode does not match a valid ISO 3166-1 alpha-2 country code.
  • The name of the attribute (CountryCode) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'JobTitle'.
  • JobTitle exceeds 255 characters.
  • The name of the attribute (JobTitle) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'LanguageCode'.
  • LanguageCode does not match a valid language code as listed above.
  • The name of the attribute (LanguageCode) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'Location'.
  • Location exceeds 255 characters.
  • The name of the attribute (Location) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'MiddleName'.
  • MiddleName exceeds 255 characters.
  • The name of the attribute (MiddleName) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'Phone'.
  • Phone exceeds 255 characters.
  • The name of the attribute (Phone) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'PostalCode'.
  • PostalCode exceeds 255 characters.
  • The name of the attribute (PostalCode) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'ProvinceCode'.
  • ProvinceCode contains the country prefix
  • ProvinceCode is not a valid value for the country specified in CountryCode
  • CountryCode is blank or not provided (required for ProvinceCode to work).
  • ProvinceCode does not match an ISO 3166-2 province code.
  • The name of the attribute (ProvinceCode) within the attribute statement does not match our documentation exactly. This is case-sensitive.

We were unable to provision a user. There was a problem with 'SupervisorIdentifier'.
  • User specified in SupervisorIdentifier isn't found in Absorb.
  • User specified in SupervisorIdentifier isn't an admin/supervisor in Absorb.
  • Incorrect SupervisorIdentifier type provided (e.g. if portal's SSO settings have their Id Property set as Email Address, but SupervisorIdentifier is an External Id)
  • The name of the attribute (SupervisorIdentifier) within the attribute statement does not match our documentation exactly. This is case-sensitive.

Response Signature could not be Verified
  • If this starts when provisioning is enabled, but had worked prior; Line/Carriage breaks may exist on one or more attributes. Ensure that all attributes being sent are sent on a single line.

 

For more information about provisioning, you can refer to the Incoming SAML 2.0 SSO Account Provisioning article.

Was this article helpful?
0 out of 1 found this helpful

Comments

0 comments

Article is closed for comments.

Related articles

Related articles