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.

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.
   
5. Click the Allow users to be updated via SSO SAML user provisioning button to streamline User management and ensure User accounts are created or updated dynamically without requiring manual intervention.
   

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:
   • https://PortalURL/api/rest/v2/authentication/saml
     • You must replace 'PortalURL' from the above example with your Route details.
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.

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.

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:

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.

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:

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

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:

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:

• Troubleshooting SSO: Incoming SAML 2.0 Account Provisioning
• Troubleshooting SSO: SAML Trace

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