Single Sign On (SSO) Account Provisioning is a process where a User who does not exist in Absorb LMS can have an account generated for them at the time of first access. This account then remains in the LMS and can be used for a regular SSO login moving forwards. This document assumes you have some familiarity working with an existing incoming SAML 2.0 SSO configuration with Absorb. For more information on authenticating Users into Absorb LMS using SAML SSO, please refer to our dedicated documentation on the subject:

• Incoming SAML 2.0 Single Sign-On

Account Provisioning or User Provisioning is a process which only occurs once. Once an account has been provisioned they will exist as a regular User in the LMS and provisioning will no longer be required. This means that existing Users will not be updated by User Provisioning and any changes after provisioning would need to be made manually by an Administrator with sufficient admin permissions.

 

Setup

Accounting Provisioning is an optional inclusion for an already existing SAML SSO configuration. This section will showcase the requirements for a SAML assertion to be consumed and a new User account in Absorb LMS to be generated.

Supported SSO Modes

The following SSO Modes support SAML Account Provisioning:

• Incoming SAML Identity Provider Initiated (IdP-initiated) SSO
  • If possible Absorb recommends using SP-initiated for your SSO
  • Users will navigate to Absorb's Login URL and will be automatically redirected to the identity provider's Login URL found in Absorb's SSO configuration. Absorb will initiate the process by generating a SAML request for authentication.

• Incoming SAML Service Provider Initiated (SP-initiated) SSO
  • Users will navigate to the identity provider's login URL to enter their credentials, or optionally to Absorb's Login URL to be automatically redirected to the Login URL found in Absorb's SSO configuration if Automatically Redirect is enabled.

 

Order of Operations

The following outlines the process for authenticating with SAML SSO and provisioning a new User account in the event that a matching User is not found. The below process assumes either service-provider initiated SSO or identity-provider initiated SSO with the Automatically Redirect option turned on (although this is not strictly required).

1. User navigates in their browser to the Portal URL and is redirected to the Identity Provider (IdP) login page
2. The IdP identifies the User.
   • The User would usually be prompted for their credentials unless they have an active login session for your IdP.
3. The IdP generates a POST of a signed SAML Response with a SAML Assertion to https://PortalURL/api/rest/v2/authentication/saml 
4. Absorb verifies the SAML Response using the public x.509 Key and Signature Type values stored in Absorb's SSO configuration
   
   
5. Absorb attempts to authenticate the User into Absorb by comparing a passed "NameID" in the SAML assertion with the Id Property stored in Absorb's SSO configuration. If a matching LMS User is found that User will be logged into the LMS and the SSO process will terminate here.
6. If the authentication verification is successful but no LMS User can be identified, Absorb will check if Account Provisioning has been enabled in the SSO configuration. If so, Absorb will check the SAML response for an attribute statement to attempt to provision a new User with the attributes specified. If the Account Provisioning is successful, the newly created User is logged into the Absorb system.
   • In the case that User Provisioning is NOT enabled for the route, the User is directed to the existing Absorb error page outlining the issue (i.e. no corresponding user in Absorb).
   • In the case that the User could not be provisioned, the User is directed to an Absorb error page outlining the provisioning issue (see error handling below).

Welcome Emails for Provisioned Accounts

Users provisioned via SSO will not receive a welcome email from the LMS. This is intended to ensure the User has a seamless experience navigating between your IdP and your Absorb LMS.

 

Authentication Statement

The SAML Response statement must include a name identifier (ID Property) that corresponds to one of the following LMS User properties:

In some IdP systems the ID Property is communicated as NameID.

Absorb will compare the NameID property that is passed in the SAML assertion with the ID Property chosen in your SSO configuration. If a User with an ID Property that matches the NameID passed in the SAML assertion is found; that User will be successfully authenticated into the LMS.

If no matching User is found, Absorb will then, and only then, consume the included attributes in the SAML assertion to provision a new account. It is important to note that, for this reason, included attributes are only used to provision new accounts, not update existing ones.

 

Attribute Statement

When issuing a SAML Single Sign-On assertion, attribute information may be provided alongside the authentication statement. If User Provisioning is not set up for the route, this information is generally ignored as it does not pertain to the User authentication itself. However, the information is required for provisioning to work on a given route as it contains the necessary information to create an account in Absorb.

Absorb only supports a 'schema-less' attribute structure that maps to LMS User Fields. The corresponding User Field cannot be derived by reference to a standard schema in the attribute definition. This is intended to provide the most flexibility for Custom Fields and unconventional mappings between corporate User information and Absorb User information.

In order for a User to be provisioned in the LMS when enabled for the route, attribute names and values in the SAML attribute statement must follow a pre-defined Absorb structure as outlined below. The attributes must be included in the order showcased below. As an example ProvinceCode cannot come before CountryCode.

Attribute names and their corresponding accepted values:

Attribute Name	Notes	Requirement
Username	The username. Must be unique, and between 1 and 255 characters	REQUIRED
FirstName	The user's first name. Must be between 1 and 255 characters	REQUIRED
LastName	The user's last name. Must be between 1 and 255 characters	REQUIRED
DepartmentId	A GUID that matches a department's GUID within Absorb. GUID values can be supplied in any of the 5 acceptable formats described in the "Remarks" section here. Note: only one of DepartmentId or ExternalDepartmentId attributes are required, not both.	REQUIRED* (see notes)
ExternalDepartmentId	Matches a department's external Id within Absorb. Note: only one of DepartmentId or ExternalDepartmentId attributes are required, not both.	REQUIRED* (see notes)
Address	Address, max 4000 characters	Optional
Address2	Address, line 2, max 4000 characters	Optional
City	City, max 255 characters	Optional
CountryCode	The ISO 3166-1 alpha-2 code for the country https://www.nationsonline.org/oneworld/country_code_list.htm	Optional
DateHired	ISO-8601 date (yyyy-mm-dd)	Optional
Email	Correctly formatted email address, max 255 characters Note: If the SSO Id Property in Absorb is set to Email Address, then this field becomes required.	Optional * (see notes)
EmployeeNumber	Employee Number, string, max 255 characters Note: If the SSO Id Property in Absorb is set to Employee Number, then this field becomes required.	Optional * (see notes)
Gender	"0" - N/A "1" - Male "2" - Female	Optional
JobTitle	Job Title, max 255 characters	Optional
LanguageCode	2-letter language code, except for Chinese (Traditional) See the Language section below for more information.	Optional
Location	Location, string, max 255 characters	Optional
MiddleName	Middle name, max 255 characters	Optional
Phone	Phone Number, max 255 characters	Optional
PostalCode	Postal/zip code, max 255 characters	Optional
ProvinceCode	The ISO 3166-2 code for the province https://www.iso.org/obp/ui/#iso:code:3166:CA	Optional
SupervisorIdentifier	Will identify the Supervisor using the "Id Property" specified in the SAML configuration See the Supervisor section below for more information.	Optional
UserExternalId	External id, max 255 characters Note: If the SSO Id Property in Absorb is set to External Id, then this field becomes required.	Optional * (see notes)
Custom Fields in Absorb	See the Custom Fields section below	Optional

 

Transmitting GUID Values

GUID values can be supplied in any of the 5 acceptable formats showcased here:

 

Password

There is no password attribute for provisioning, but passwords are required by Absorb to create an account. When a User is provisioned, a secure, random password is generated using a Generate Password method. For more about the Generate Password method, click here. 

The length of the password is set to a minimum of 40 characters long, and minimum non-alphanumeric characters to 5.

Password Reset Requests

If no email address is provided during provisioning, the User will be unable to generate a reset password email, but will still be able to log in via SSO.

 

Department

Departments for the User are required and can be set using one of the following attributes:

• DepartmentId: A guid that matches a department's Id.
• ExternalDepartmentId: Matches a department's external Id

Department is a required field for Account Provisioning. You must specify it by passing either the DepartmentId attribute or the ExternalDepartmentId attribute in your SAML assertion. If both the DepartmentId and ExternalDepartmentId are provided, the DepartmentId will be the one that will be used.

 

Admin Access/Roles

Users provisioned via SSO are only granted learner access to the LMS. Administrative privileges can’t be assigned via SSO User Provisioning.

 

Supervisor

In order to optionally include the Supervisor for the User, the attribute value provided for the supervisor must match a User identifier in Absorb that corresponds with the Id Property in your SSO setup. The format for the Supervisor attribute is as follows:

• SupervisorIdentifier: Will identify the Supervisor using the "Id Property" specified in the SAML configuration, leveraging one of the following Id Properties:
• Id
• Username
• Email Address
• External Id
• Employee Number

For example, if the Id Property specified in your SSO setup is the Absorb User Id, the value for the SupervisorIdentifier attribute must be a valid GUID that matches an Absorb User Id. If the Id Property specified in your SSO setup is the username, email address, external Id, or employee number, these fields may be any valid string between 1 and 255 characters which uniquely matches an existing Absorb User.

Duplicate Supervisor Identifiers

Email address, employee number, and external Id fields do not have unique requirements or validations in Absorb. If the SupervisorIdentifier value provided matches multiple LMS Users; User Provisioning will halt and result in an error.

 

CountryCode

Country and province for the User can optionally be supplied using the ISO-3166 standard codes for the country and province:

• Characters for country are case-insensitive.
• A complete list of country codes can be found online here: https://www.nationsonline.org/oneworld/country_code_list.htm
• For example, both CA and ca would be accepted for Canada.

 

ProvinceCode / StateCode

ProvinceCode requires CountryCode to be included in the SAML Assertion. If you include ProvinceCode without CountryCode it will not work as intended. Format restrictions for the ISO 3166-2 ProvinceCode include:

• Must exclude the country prefix for the province code.
• When the province code following the country prefix has leading zeros, these MUST be included.
• Must be a valid value for the country defined by the CountryCode.
• Characters for province are case-insensitive.

In example 'CA-AB' is the supported format for Alberta, Canada. The country prefix for the ISO 3166-2 code (CA-) must be excluded from the province code so only 'AB' is included in the attribute statement. 01 is the supported format for Central Singapore, which excludes the country prefix but keeps the leading zeros for the province (SG-01).

 

Language

Possible language codes are as follows:

Code	Name
en	English
fr	French
es	Spanish
ja	Japanese
ar	Arabic
zh-Hant	Chinese (Traditional)
zh	Chinese (Simplified)
it	Italian
de	German
nl	Dutch
pl	Polish
pt	Portuguese
ru	Russian
tr	Turkish
th	Thai
ko	Korean
vi	Vietnamese
mn	Mongolian
sv	Swedish
cs	Czech
fi	Finnish
he	Hebrew
el	Greek
da	Danish
no	Norwegian
hu	Hungarian
ro	Romanian
sk	Slovak
ms	Bahasa Melayu
hi	Hindi

 

Custom Fields

Specify Custom Fields by their internal name (e.g. String1, Decimal1, DateTime1, Bool1).

In order to easily support identifying the Custom Field internal name corresponding with your custom User profile fields, these internal names can be viewed by system admins in portal settings:

Accepted values for Custom Field types are as follows:

• Text fields should be no longer than 255 characters.
• True/False fields should be given as "True" or "False".
• Number fields accept whole numbers between -90000000000000 and 90000000000000.
• Decimal fields accept real numbers between -90000000000000 and 90000000000000.
  • Max 2 decimal places.
  • Max 14 digits including any digits after the decimal.
• Date fields should be provided in ISO-8601 date format (yyyy-mm-dd).

 

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.

 

Authentication Errors

Please see existing SAML SSO support documentation for information on validations performed on the SAML assertion. 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:

 

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.

 

Preparing and Analyzing a SAML Trace

When investigating Account Provisioning errors. It can be useful to capture a SAML trace and observe the exact information being transmitted in the SAML assertion. To capture a SAML trace you will need a browser compatible tool which analyzes SAML and network events. A free browser addon compatible with Google Chrome would be:

• saml-tracer

With your tool prepared you can now analyze network events and parse out a SAML event. The tool saml-tracer must be open before attempting to capture the event as it does not look back historically. With the tool open, proceed through the following series of steps:

1. Confirm the SAML trace tracking tool is open/capturing.
2. Navigate through your Account Provisioning flow.
3. Encounter the error you are troubleshooting.
4. View the tool and parse for a recent SAML event.
   
5. Select the SAML event you want to investigate. Often this will be a POST pointing at an authentication endpoint. In saml-tracer you will observe SAML on the right hand side as well.
6. Various elements can be observed for the SAML event. Saml-tracer breaks out the different sections of the events into the following sections: HTTP, Parameters, SAML and Summary
   
7. Under the HTTP section, confirm the POST is looking at the correct location.
8. Under the SAML section the following may be relevant:
   
   • The X509Certificate section. Confirm this contains the correct X509/Key.
     
   • NameID Format. Confirm the correct identity property and value are supplied in this section.
     
   • Under AttributeStatement there will be the attributes sent for Account Provisioning. Confirm all required attributes are included, that they aren't derived from a schema and that the names are exactly as above in this document.
     
9. Under the Summary section you can observe information from the other panels in a convenient GUI. It can be worthwhile to investigate the SAML section prior to the Summary just in case there are notable differences.

Through the process of analyzing a SAML trace the issue often becomes apparent. Whether that is a missing SAML assertion all together, an out-dated X509 certificate or the attribute statement includes the usage of an XML Schema. Parsing the actual SAML assertion itself to confirm each portion is being communicated as intended is worthwhile. At times if you observe a difference between what is configured in your IdP and what is sent in the SAML assertion. This may indicate there are server caching issues and a restart on the side of your IdP is required to POST the intended information during the Account Provisioning process.

Sources & References

The following articles are referenced in the creation of this document:

• https://learn.microsoft.com/en-us/dotnet/api/system.guid.parse?view=net-7.0&redirectedfrom=MSDN#System_Guid_Parse_System_String_
• https://learn.microsoft.com/en-us/dotnet/api/system.web.security.membership.generatepassword?view=netframework-4.8.1
• https://www.iso.org/obp/ui/#iso:code:3166:CA
• https://www.nationsonline.org/oneworld/country_code_list.htm