Introduction
The main purpose of establishing a Single Sign On (SSO) process with Absorb is to allow your users a single point of entry into your system while providing them access to multiple other independent systems. With this process a user logs in with a single ID to gain access to a multitude of other systems without being prompted for different usernames and passwords. For more information on authenticating users into Absorb LMS through a SAML SSO, please refer to our dedicated documentation on the subject:
Incoming SAML 2.0 Single Sign-On
In a typical incoming SSO setup, the primary identity management will lay with your Identity Provider of choice. With that said, an SSO implementation still requires accounts to exist in the Service Provider (Absorb LMS); single sign-on just makes the connection between these two accounts transparent for the end-user.
Absorb's Incoming SAML 2.0 SSO Account Provisioning functionality takes the hassle out of managing new users in the LMS, by automating the process of creating a new Absorb user account in the event that no existing account is detected during the SSO authentication stage.
Note: 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 rights.
Assumptions
This document assumes you have some familiarity working with an existing incoming SAML 2.0 SSO with Absorb. For more information on this subject, we would recommend reviewing our dedicated documentation on the subject: Incoming SAML 2.0 Single Sign-On
Contents
User Flow
The following outlines the process for authenticating through a 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).
- User navigates in their browser to the Portal URL and is redirected to the Identity Provider (IdP) login page
- The IdP identifies the user (i.e. user would usually be prompted for their credentials if they do not already have an active session in your IdP)
- The IdP generates a POST of a signed SAML Response with a SAML Assertion to https://PortalURL/api/rest/v2/authentication/saml
- Absorb verifies the SAML Response using the public x.509 Key and Signature Type values stored in Absorb's SSO configuration
- 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 (i.e. attempts to match NameId with an existing LMS Username). If a matching LMS user is found that user will be logged in to the LMS and the SSO process will terminate here.
- 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).
Note: 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 corporate IdP and your Absorb LMS.
Setup
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.
Authentication Statement
The SAML Response statement must include a name identifier (NameId property) that corresponds to one of the following LMS user properties:
- Absorb User Id
- Username
- Email Address
- External Id
- Employee Number
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 is found with a User Id / Username / Email Address / External Id / Employee Number (depending on your selection) matching the NameId passed in the SAML assertion, 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 information. 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.
Note: 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 user profile fields and unconventional mappings between corporate user information and Absorb user information.
While the SAML V2.0 attribute structure is agnostic with respect to the types and structure of the attributes included, 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.
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 See the Country & Province/State section below for more information. |
Optional |
DateHired |
ISO-8601 date (yyyy-mm-dd) |
Optional |
|
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 |
|
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 See the Country & Province/State section below for more information. |
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 |
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 the Membership. Generate Password method described here.
The length of the password is set to a minimum of 40 characters long, and minimum non-alphanumeric characters to 5.
Note: 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" - [Mutually Exclusive] A guid that matches a department's Id (scope reduction)
- "ExternalDepartmentId" - [REQUIRED] Matches a department's external Id
Since Department is a required field you must specify it by the department Id or the External Id is mandatory, yet only one identifying property will be used. If both the Department ID and External ID are provided, the department Id will be the one that will be used.
GUID values can be supplied in any of the 5 acceptable formats described here: https://msdn.microsoft.com/en-us/library/system.guid.parse(v=vs.110).aspx
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" - [Optional] 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 (see aforementioned acceptable formats for GUIDs) 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.
Note: email address, employee number, and external Id fields do not have unique requirements or validations to Absorb. If the SupervisorIdentifier value provided matches multiple LMS users, the user provisioning will halt and result in an error.
Attribute Notes
Country & Province / State
Country and province for the user can optionally be supplied using the ISO-3166 standard codes for the country and province:
CountryCode
[Optional] The ISO 3166-1 alpha-2 code for the country
- 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
[Optional when country is supplied] The ISO 3166-2 code for the province; format restrictions 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
For example, AB is the supported format for Alberta, Canada; the country prefix for the ISO 3166-2 code (e.g. CA-) must be excluded from the province code. 01 is the supported format for Central Singapore, which excludes the country prefix but keeps the leading zeros for the province (e.g. 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
Authentication Errors
If there are errors authenticating the user via SSO, these errors are logged in Absorb, and the user will be presented with a page describing the issue. Please see existing SAML SSO support documentation for information on validations performed on the SAML assertion.
Specific error messages displayed to end-users can be customized by a system admin in the admin Translations settings for supported learner-site languages. Specific page styling for error pages can be customized by a system admin from the Templates report; this will leverage the template corresponding to the department assigned to the route the user is directed to, or the root department if no department is assigned to that route.
Given no attribute statement is included in the SAML assertion, 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 below for accepted attribute values
- e.g. ProvinceCode is provided but CountryCode is not provided
- e.g. ProvinceCode does not belong to the provided country
- e.g. 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
Error Message |
Potential Cause(s) |
No matching Absorb user was found. |
|
We were unable to provision a user. |
|
We were unable to provision a user. There was a problem with 'Username'. |
|
We were unable to provision a user. There was a problem with 'Email'. |
|
We were unable to provision a user. There was a problem with 'EmployeeNumber'. |
|
We were unable to provision a user. There was a problem with 'UserExternalId'. |
|
We were unable to provision a user. There was a problem with 'Gender'. |
|
We were unable to provision a user. There was a problem with 'DateHired'. |
|
We were unable to provision a user. There was a problem with 'Department Id'. |
|
We were unable to provision a user. There was a problem with 'ExternalDepartmentId'. |
|
We were unable to provision a user. There was a problem with 'CustomFields'. |
|
We were unable to provision a user. There was a problem with 'FirstName'. |
|
We were unable to provision a user. There was a problem with 'LastName'. |
|
We were unable to provision a user. There was a problem with 'Address'. |
|
We were unable to provision a user. There was a problem with 'Address2'. |
|
We were unable to provision a user. There was a problem with 'City'. |
|
We were unable to provision a user. There was a problem with 'CountryCode'. |
|
We were unable to provision a user. There was a problem with 'JobTitle'. |
|
We were unable to provision a user. There was a problem with 'LanguageCode'. |
|
We were unable to provision a user. There was a problem with 'Location'. |
|
We were unable to provision a user. There was a problem with 'MiddleName'. |
|
We were unable to provision a user. There was a problem with 'Phone'. |
|
We were unable to provision a user. There was a problem with 'PostalCode'. |
|
We were unable to provision a user. There was a problem with 'ProvinceCode'. |
|
We were unable to provision a user. There was a problem with 'SupervisorIdentifier'. |
|
Response Signature could not be Verified |
|