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.

 

Enabling Account Provisioning

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.

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.

 

To enable Account Provisioning on your supported SSO configuration, follow these steps:

  1. From the Admin Experience open the Account menu and select Portal Settings. The Edit Client page will open.
  2. From the Edit Client page, click Manage SSO Settings. The Manage Single Sign-On Settings page will open.

  3. Expand an existing SSO configuration, or create a new one and scroll to the bottom to find the Allow User Provisioning toggle.
  4. Click the toggle to ON to enable User Provisioning.
Additional Configuration Required

Turning the Account Provisioning toggle to ON does not complete the required configuration. For Account Provisioning to work as intended, external configuration on the side of your SSO provider must be completed. The required steps may differ between configurations or SSO providers.

 

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 toggle turned ON (although this is not strictly required).

The Account Provisioning flow order of operations is as follows:

  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:
  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. If it is 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 OFF 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.

 

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 an ID Property. In your SAML assertion, ID Property is communicated as Name ID and may be labelled Name Identifier on the side of your SSO provider. ID Property on the Absorb side of the configuration must correspond to one of the following LMS User properties:

 

If you are preparing your SAML assertion, or looking at a SAML trace of the event, you will see something like:

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

or

urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

 

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.

Provisioning Occurs Only Once

It is important to keep in mind that a successful instance of Account Provisioning will only occur a single time, per account, unless an account is deleted from Absorb. After a User has been successfully provisioned SSO login attempts will only trigger the regular SSO login flow, as Account Provisioning is no longer required. SSO login will not apply changes in the Attribute Statement to the User.

 

Communicating User Details for Provisioning

So that a User can be successfully created in your Portal, the SAML assertion that includes NameID for regular SSO authentication must also include additional information. User details such as Username, Department or similar are communicated in a SAML assertion as Attributes. In a SAML assertion a list of Attributes are included underneath a section known as the Attribute Statement. Absorb looks for the Attribute Statement when creating a User for the purposes of Account Provisioning.

If User Provisioning is not enabled the Attribute Statement is generally ignored as it does not pertain to the User authentication itself. However, the information is required for provisioning to work 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. When preparing your Attribute Statement it is essential that the Attribute Name is exactly as listed.

 

In the above example the FirstName Attribute is used and the given value is 'Josh'. If the Attribute Name or Value was instead 'http://schemas.microsoft.com/identity/claims/firstname' or similar, this would not work as intended for Account Provisioning.

Required User Details

All Users have a certain number of required fields. Account Provisioning is required to include the following Attributes or a User cannot be provisioned, even if the SSO configuration is working correctly.

  • Username, First Name, Last Name, and Department ID or External Department ID.
  • If NameID is not Username, the ID Property selected is also a required Attribute.
    • As an example if Email Address is your ID Property, you must include Email Address in your Attribute Statement.

 

Attribute Statement

In order for a User to be provisioned Attribute Names and Values in the SAML Attribute Statement must follow a pre-defined Absorb structure as outlined below. Please advise the following information:

  • The Attributes must be included in the order showcased below.
    • As an example ProvinceCode cannot come before CountryCode.
  • The Attribute Name is case sensitive, and must be included in your Attribute Statement exactly as indicated below. As an example:
    • <Attribute Name="Username">
    • <Attribute Name="FirstName">
    • <Attribute Name="LastName">
    • <Attribute Name="ExternalDepartmentId">

 

Attribute Names and their corresponding accepted values:

Attribute Name

Requirement

Description

Username

REQUIRED

The Username. Must be unique, and between 1 and 255 characters.

FirstName 

REQUIRED

The User's First Name. Must be between 1 and 255 characters.

LastName 

REQUIRED

The User's Last Name. Must be between 1 and 255 characters.

DepartmentId

REQUIRED*

A GUID that matches a Department's GUID within Absorb.

*only one of DepartmentId or ExternalDepartmentId are required, not both.

ExternalDepartmentId

REQUIRED*

Matches a department's External Id within Absorb.

*only one of DepartmentId or ExternalDepartmentId are required, not both.

Address 

Optional

Address, max 4000 characters.

Address2 

Optional

Address, line 2, max 4000 characters.

City 

Optional

City, max 255 characters.

CountryCode

Optional

The ISO 3166-1 alpha-2 code for the country:

https://www.nationsonline.org/oneworld/country_code_list.htm

DateHired 

Optional

ISO-8601 date (yyyy-mm-dd).

Email 

Optional*

 

Correctly formatted Email Address, max 255 characters.

*If Id Property in Absorb is set to Email Address, then this field becomes required.

EmployeeNumber 

Optional*

 

Employee Number, string, max 255 characters.

*If Id Property in Absorb is set to Employee Number, then this field becomes required.

Gender 

Optional
  • "0" - N/A
  • "1" - Male
  • "2" - Female

JobTitle 

Optional

Job Title, max 255 characters.

LanguageCode

Optional

2-letter language code, except for Chinese (Traditional).

See the Language section below for more information.

Location 

Optional

Location, string, max 255 characters.

MiddleName 

Optional

Middle Name, max 255 characters.

Phone 

Optional

Phone Number, max 255 characters.

PostalCode 

Optional

Postal/Zip Code, max 255 characters.

ProvinceCode

Optional

The ISO 3166-2 code for the Province:

https://www.iso.org/obp/ui/#iso:code:3166:CA

SupervisorIdentifier

Optional

Will identify the Supervisor based on their ID Property.

See the Supervisor section below for more information.

UserExternalId 

Optional*

 

External Id, max 255 characters.

If Id Property in Absorb is set to External Id, then this field becomes required.

Custom Fields in Absorb

Optional

See the Custom Fields section below.

 

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 LMS to create an account. When a User is provisioned, a secure, random password is generated using a generate password method.

  • For more information 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.

Provisioned Users as Administrators

Once a User has been successfully provisioned. They are still able to become Administrators but this role, or others, must be assigned manually by an Admin of equal or higher permissions.

 

Supervisor

It is possible to optionally assign a Supervisor in the information used to provision a User. The Attribute Value supplied is based on the ID Property used in the SSO configuration. The ID Property value supplied must match an existing Supervisor.

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 Username, Email Address, External ID, or Employee Number, the same must be provided as the SupervisorIdentifier.

 

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 ISO-3166 standard codes:

 

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

The internal names of Custom Fields can be viewed by System Admins in Portal Settings under the Custom Fields tab:

 

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.

For more information about troubleshooting Account Provisioning please advise the following documentation:

 

Sources & References

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

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