Incoming SAML 2.0 SSO Account Provisioning

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:

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:

 

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:

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 for accepted attribute values.
  • 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, 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

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

 

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:

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:

Was this article helpful?
2 out of 3 found this helpful