1. Absorb Help Center
  2. Absorb LMS Knowledge Base
  3. Portal Settings
  4. Manage SSO Settings

Incoming SAML 2.0 SSO Account Provisioning

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

  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 (i.e. user would usually be prompted for their credentials if they do not already have an active session in 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 (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.
  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).

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

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

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

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

Articles in this section

See more
Was this article helpful?
0 out of 1 found this helpful