Incoming SAML 2.0 SSO Account Provisioning

Follow

Please note this feature is only available for clients that have upgraded to the New Learner Experience

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

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/account/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
    • 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.
  • Incoming SAML Service Provider Initiated (SP-initiated) 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.

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 about a principal may be provided as an adjunct to authentication information. If user provisioning is not setup for the route, this information is generally ignored as it does not pertain to the authentication mechanism itself. 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.

Note: Absorb currently 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: e.g.:http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname This is intended to provide the most flexibility for your Absorb LMS custom user profile fields and unconventional mappings between your corporate user information and Absorb user information.

Default Fields

The exact field names expected as attribute properties are listed below in double-quotes. These field names and values must be provided as assertion attributes described in the 'SAML V2.0 Technical Overview: http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0-cd-02.html#4.4.3.Attribute. All fields are strings, and will be trimmed before use.

Attribute names and their corresponding accepted values:

  • "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
  • "Email" - [Optional] Correctly formatted email address
  • "MiddleName" - [Optional] Middle name, max 255 characters
  • "JobTitle" - [Optional] Job Title, max 255 characters
  • "EmployeeNumber" - [Optional] Employee Number, string, max 255 characters
  • "Phone" - [Optional] Phone Number, string, max 255 characters
  • "Location" - [Optional] Location, string, max 255 characters
  • "Address" - [Optional] Address, max 4000 characters
  • "Address2" - [Optional] Address, line 2, max 4000 characters
  • "City" - [Optional] City, max 255 characters
  • "PostalCode" - [Optional] Postal/zip code, max 255 characters
  • "UserExternalId" - [Optional] External id, max 255 characters
  • "Gender" - [Optional] "0" - N/A, "1" - Male, "2" - Female
  • "DateHired" - [Optional] ISO-8601 date (yyyy-mm-dd)
  • "TerminationDate" - [Optional] ISO-8601 date (yyyy-mm-dd)

Password

When a user is provisioned, a secure, random password is generated using the Membership.GeneratePassword method described here: https://docs.microsoft.com/en-us/dotnet/api/system.web.security.membership.generatepassword
The length of the password is set to a minimum of 40 characters long, and min non-alphanumeric characters to 5. 

Note: if no email address is provided during the 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 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

Specifying the department by it's Id or External Id is mandatory, but only one identifying property will be used. If multiple are supplied, the department Id will be treated as the source of truth. 
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 

Roles

All users provisioned via SSO will be provided learner access ONLY. 

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, "CA" for Canada
  • "ProvinceCode" - [Optional when country is supplied] The ISO 3166-2 code for the province; format restrictions include:
    • 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.
    • For example, "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")
    • For example, both "CA" and "ca" would be accepted for "Canada"
    • 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 country and province are case-insensitive

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 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 uniqueness requirements or validations in Absorb. If the SupervisorIdentifier value provided matches multiple LMS users, the user provisioning will halt and result in an error. 

Language

  • "LanguageCode" - [Optional] 2-letter language code, except for Chinese (Traditional) 
    Possible language codes are as follows (Abbreviation, 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

All custom fields are specified by their internal name of "String{1-30}", "Decimal{1-5}", "DateTime{1-5}", or "Bool{1-5}". In order to easily support identifying the custom field internal name corresponding with your custom user profile fields, these internal names can now 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 & Time, and Date fields should be provided in the ISO-8601 date format

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 New Learner Experience (NLE) 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

Account Provisioning Errors

Assuming the SAML authentication is verified but the user does not exist in the LMS, the provisioning will be attempted; however, any issues provisioning the user based on the information provided in the SAML assertion's attribute statement will result in a failure to provision the user account. In this case, the user will be directed to an error describing the user provisioning issue, specifically:

  • Notification that the there was an issue creating their account
  • Information on the 'culprit' attributes that resulted in a failure to provision the user

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 collectivises, etc. Please review existing LMS country/province dropdowns to view all supported countries and their respective sub-divisions.

 

Published on
Have more questions? Submit a request

0 Comments

Article is closed for comments.