Incoming SAML 2.0 Account Provisioning is the process of taking User credentials from one location and using them to create an account in another location based on an Identity Property such as Email Address or Username. When building out an Account Provisioning flow it is possible to encounter errors, often alongside specific error messages. This document is focused on identifying and resolving SAML 2.0 SSO issues with Account Provisioning.

For more information about configuring SAML 2.0 SSO click here.
For more information about configuring SAML 2.0 SSO Account Provisioning click here.

Error Handling and Troubleshooting

When attempting Account Provisioning you may be required to troubleshoot the configuration. Often an error is encountered due to a systematic or structural issue and once it has been resolved; the issue is unlikely to reproduce.

An example of this would be if the Attribute Statement alongside the SAML assertion is using an 'XML.Schema' for the value of each Attribute instead of the actual value itself. Once the SAML assertion is updated provisioning attempts moving into the future should succeed.

Account Provisioning Advisory

Before troubleshooting your Account Provisioning flow, confirm that a regular SSO authentication works as intended. If an existing User cannot authenticate through your SSO configuration Account Provisioning may be failing for this reason.

This section contains different types of errors and best practices for troubleshooting them:

Authentication Errors

For Account Provisioning to work as intended, the SSO connection must be capable of successfully authenticating an existing User. If you are encountering the 'No matching LMS User was found' error when attempting to provision a User, test a User that does not need to be provisioned. If neither User can successfully SSO into the Portal, the configuration may require troubleshooting before Account Provisioning.

In the case no Attribute Statement is included in the SAML assertion intended for Account Provisioning, the User will be directed to the existing 'No User Found' error type, as indicated in the sample screenshot below:

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

SkillSync requires that the value passed as 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 SkillSync Portal

This error is only possible if the Id Property set in your SSO config is NOT Username (e.g. Email, External Id, or SkillSync Id); if that value does not exist in SkillSync, 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 here for accepted attribute values. Possible causes of this error may be:

ProvinceCode is provided but CountryCode is not provided.
ProvinceCode does not belong to the provided country.
CountryCode or ProvinceCode are provided but do not match a supported country or province code or format.
- At the time of writing, SkillSync 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, SkillSync 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

Certain messages will be presented at the time of attempting to perform Account Provisioning. It can be useful to capture a screenshot of the error encountered to reference it during your troubleshooting.

No matching SkillSync 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.
This may indicate there is a User account with matching details, that is inactive in the Portal. Please rule out that there are not any inactive Users with matching details or Identity Properties.
Sometimes this 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. SkillSync 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 SkillSync.
User specified in SupervisorIdentifier isn't an admin/supervisor in SkillSync.
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.

Special Characters & Encoding Issues

When preparing a SAML assertion, sometimes special characters can become corrupted, or malformed. As an example the characters @ or & could appear incorrectly, or as different characters entirely. It is important to rule out any potential encoding issues with the data that is being included in a SAML assertion. An example circumstance may be:

Raw User data is stored in Location A, using the ASCII encoding standard. The data from Location A is transferred to Location B, then prepared for the SAML assertion. Location B uses the UTF-8 encoding standard and as a result, it is possible text data from one location becomes changed when moved to another. In this example, it is important to confirm the data is exactly as intended when going into the SAML assertion and that all special characters are used only when required.

SAML Trace Analysis

A SAML trace is a captured series of events, presented as a log of text that allows you to review a SAML interaction. As it relates to Account Provisioning a SAML trace can be used to confirm a POST is distributing a SAML assertion to the correct target/destination. Additionally a SAML trace can review if an Attribute Statement is being distributed correctly, and what the Attribute Names and values are.

Capturing a SAML trace requires a browser add-on, or a browser capable of viewing SAML events. For more information about capturing a SAML trace, please advise our article on the topic here:

Troubleshooting SSO: SAML Trace

Troubleshooting SSO: Incoming SAML 2.0 Account Provisioning