Troubleshooting Incoming SAML SSO

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

Some errors discussed in this article contain examples of SAML traces, which can be used to investigate Account Provisioning errors. For more information on SAML traces and how to complete a SAML trace, please see the article here.

Common SSO Configuration Errors

When setting up SSO, you may encounter errors during the configuration process. The table below lists some common errors and associated details:

Error	Details
Key (X509 Certificate)	Make sure that there are no line breaks or spaces in the key when it is entered to SkillSync; this should exactly match what is in the SAML Response.
Id Property	The value of this field must match the value of the NameID field in the SAML Response. Once this match is confirmed, it is used to match to a user in the LMS using the Id Property as defined in your SSO configuration settings within SkillSync.
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

This section covers HTTP Code: 200 errors, possible explanations, and potential solutions you can implement. 

200: Multiple Users

HTTP Code: 200 - Multiple Users
Error	SkillSync 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 SkillSync 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: 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: https://company.myabsorb.com/ https://company.myabsorb.com/# https://company.myabsorb.com/#/dashboard 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	SkillSync 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

This section covers HTTP Code: 302 errors, possible explanations, and potential solutions. 

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

HTTP Code: 302 - No Matching User Found
Error	SkillSync Login Screen: "We apologize; no matching SkillSync 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 receives an error on the SkillSync Dashboard after selecting the App on the SSO portal.
Solution	If User Provisioning is DISABLED (Error reads: We apologize; no matching SkillSync 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 SkillSync 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 (e.g., 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 SkillSync. 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 SkillSync 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. SkillSync does not support Encrypted SAML Responses. In ADFS, removing the entry under the encryption tab of the ADFS SSO properties for the SkillSync connection and moving them to the Signature tab should help, as SkillSync does support signed responses. B. Update the signature key in SkillSync 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 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 SkillSync 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/SkillSync%20LMS/[someid]

Note: You can zoom in by hovering your cursor over the image.

Error Example - Provisioning Disabled	Solution Example  - Provisioning Disabled

302: Response Signature could not be Verified

HTTP Code: 302 -  No Matching SkillSync User Was Found (Response Signature Error)
Error	SkillSync 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 SkillSync. The SAML Response is being re-used. SkillSync performs a one-time-use check. The timing of the SAML Response doesn't fall within the timeframe specified in the SAML Response.
Solution	SkillSync 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 SkillSync 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

Note: You can zoom in by hovering your cursor over the image.

Solution Example

HTTP Code: 400

This section covers HTTP Code: 400 and 403 errors, possible explanations, and potential solutions. 

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 SkillSync on an IdP initiated SSO set up (e.g. with Microsoft Azure or ADFS). The Login URL should not be a SAMLRequestURL. If the client wants the SSO to know who the User is, then they need Service Provider Initiated SSO set up.
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/SkillSync%20LMS/[someid]

Error Example

403: Site Can't Be Reached

HTTP Code: 403
Error	Upon entering the Username and Password for SSO Login, the following error occurs: Click on the SkillSync 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 SkillSync SSO Setup.
Solution	Update the Consumer URL in the SSO Provider.

Note: You can zoom in by hovering your cursor over the image.

Error Example	Solution Example

SSO Deep Linking: IDP Relay State

This section covers SSO Deep Linking errors, possible explanations, and potential solutions. 

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 is 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. This is required to retain the deep linked page when a User logs in through a Deep Link. Switching to using SP Initiated over IdP Initiated is recommended to eliminate this requirement.

 

SAML SSO Support

SAML Support Disclaimer

SkillSync 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.

SAML Traces in Support Tickets

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. 

You can read more about SAML traces in the article here.

Provisioning Errors and Specific Error Messages

Information about errors and specific error messages that present during Account Provisioning can be found in the Error Handling and Troubleshooting section of this article. For more information about provisioning, you can refer to the Incoming SAML 2.0 SSO Account Provisioning article.