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.
This article discusses Incoming SAML 2.0 SSO for clients using Active Directory Federation Services (ADFS) and presents a somewhat abridged and focused version of our full Incoming SAML 2.0 Single Sign-On article. For the purposes of this article the Absorb system will act as the Service provider (SP). Your ADFS system will act as the Identity Provider (IdP).
Please note that SSO is an additional feature that usually involves an additional fee and technical resources on the client side to develop and/or configure the solution.
Disclaimer: Absorb LMS supports Incoming SAML 2.0 Single Sign-On as a feature, however we do not officially support any specific client-side (IdP) solution. Although ADFS is known to generally work with our implementation of SAML SSO, it is the client's responsibility to configure/develop and maintain their side of the integration. This will require a client resource who is knowledgeable and familiar with your particular ADFS environment. This guide is provided to our clients as a convenience only, based on our past experience working with clients who employ ADFS.
Contents:
Absorb Setup
The following variables will need to be determined and configured as part of your SSO implementation.
| Variables | Description | Requirement |
| Portal URL | This is the URL where your Absorb LMS is hosted - please contact us if you do not know this. This URL usually configured as part of your initial LMS onboarding. e.g. https://companyname.myabsorb.com OR https://some.custom.url |
Mandatory |
| Mode | Choose the principle request mode to be used, from either Service Provider Initiated or Identity Provider Initiated. | Mandatory |
| Key | The key is the x509 public certificate of the IdP that is used for the SAML assertion signature. You must configure Absorb with your IdP’s public key so that Absorb can verify your signed SAML assertions. | Mandatory |
| Id Property (Unique Identifier) | A unique identifier field chosen in the Absorb LMS to be used as the identifying NameID through the SAML assertion. Absorb can be configured to use the following as the Id Property:
|
Mandatory |
| Login URL | This is the URL where Absorb redirects users if they navigate directly to the Portal URL without an active session. If the Mode is set to Identify Provider Initiated, this redirect is only triggered when the Automatically Redirect feature is turned on. | Optional |
| Logout URL | This is the URL where Absorb redirects users when they log out of the Absorb system. | Optional |
| Automatically Redirect |
When turned on, redirects all users who navigate directly to the Portal URL to the Login URL. If not turned on, users will land on the portal's landing page. Note: For the SP Initiated Mode this setting is always enabled. |
Optional |
| RelayState | This is an optional parameter that is passed to Absorb for deep linking purposes. Please see the deep linking section for more details. | Optional |
| Assigned Routes | This field allows you to search for and select any existing routes to assign. | Mandatory |
With the exception of the Portal URL and RelayState, all of the above variables can be configured by logging in as a System Admin and navigating to the Portal Settings on the Admin portal.
From Portal Settings, there is a button in the right-side context menu labelled Manage SSO Settings. If you can't see this button, please contact your Absorb Client Success Manager to discuss enabling the feature.
Once you have clicked the button, you will be brought to the Manage Single Sign-On Settings page. Any existing configurations will appear here, as well as the option to Add a new one.
Each route (Portal URL, e.g. company.myabsorb.com) can have its own set of SSO configuration. Please see this article for more information on route-based SSO. The remainder of this article assumes we're talking about a single SSO configuration.
ADFS Setup
Login URL
Key / X509 Certificate
- Go to Certificates entry on the left tree view, right-click on Token-Signing certificate then click on View Certificate.
- On certificate details tab click on copy to file, then the certificate Export wizard launches.
- Click on next, select “Base-64 encoded X.509 (.CER)” format and save the certificate.
- Copy the certificate using a text editor or similar and enter it into the Key field in Absorb (see Setup section above).
Note: The Login URL and X509 Certificate (key) can also be retrieved from a SAML metadata file exported from ADFS.
Relying Party Trust
- Select the Relying Party Trusts folder from AD FS Management, and add a new Standard Relying Party Trust from the Actions sidebar. On the Select Data Source screen, select the last option, Enter Data about the Party Manually.
- Under Configure URL setting check the box labeled Enable Support for the SAML 2.0 WebSSO protocol. Set the service URL as https://Portal URL/api/rest/v2/authentication/saml
or https://Portal URL/Account/SAML .(See Metadata information.)
- On Choose Issuance Authorization Rules, select the Permit all users to access this relying party radio button.
- On the next two screens, the wizard will display an overview of your settings. On the final screen use the Close button to exit.
- Right-click on the relying party you’ve just created and select Properties. In the Advanced tab ensure SHA-1 is selected for the secure hash algorithm.
Claim Rules
- Select “Send LDAP Attribute as Claims” as the rule template, next, then select “Active Directory” as Attribute store. Configure “E-Mail-Addresses” to map to Outgoing claim type “E-Mail Address”. This assumes you are using Email Address as the Absorb "Id Property" (Name ID), and will need to be adjusted if using some other field.
- Select “Transform an Incoming Claim” as the rule template. Configure Claim rule name “Email to Name ID” or similar, Incoming claim type: “E-Mail Address”, Outgoing claim type: “NameID”, outgoing name ID format: “Unspecified”. Again, this assumes you are using Email Address as the Name ID - adjust the Incoming claim type as appropriate if not.
How it Works
IdP Initiated
- The user navigates to your ADFS login URL:
e.g. https://YourADFSDomain.com/adfs/ls/IdpInitiatedSignOn.aspx
If you have multiple sites setup on your ADFS then you can bypass site selection by using loginToRp=https://subdomain.myabsorb.com
e.g. https://YourADFSDomain.com/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=https://subdomain.myabsorb.com - The user logs in on your ADFS sign in page.
- ADFS POST's a SAMLResponse
to https://Portal URL/api/rest/v2/authentication/saml or https://Portal URL/Account/SAML - Absorb authenticates the SAMLResponse using the Key / X509 Certificate. If the SAMLResponse is valid and the user exists in Absorb then the user is signed in.
- If authentication fails an error is displayed to the user.
Note: If "Automatically Redirect" is enabled, an additional step may be added at the start. A user may access your Portal URL directly, and then be URL redirected to your ADFS login URL ("Login URL"). At this point the remaining steps 2-5 above apply.
Metadata
You may import Absorb's SP metadata to speed up your setup process in ADFS, though it's usually a good idea to manually check all of the items in the ADFS Setup section.
IdP Metadata
You may have already exported the certificate manually in the ADFS Setup section above, but your IdP Metadata can also be used to obtain your public X509 certificate. The X509 certificate should be added to the Key field under Portal Settings in Absorb.
Deep Linking & RelayState
Deep linking in terms of the Absorb LMS is the ability to redirect a user to a particular user content page on the Absorb LMS. Please see the Deep Linking and RelayState section in the main SAML 2.0 SSO article for a full list of supported deep links with SAML SSO.
The following are examples of deep links formulated using your ADFS IdP login URL and the RelayState variable. Note that the red highlighted portions are course and lesson GUID's that should be retrieved from your Absorb admin portal. Also note the use of URL encoding for the included parameters.
https://YourADFSDomain.com/adfs/ls/IdpInitiatedSignOn.aspx?RelayState=RPID%3Dhttps%3A%2F%2Fcompanyname.myabsorb.com%2FAccount%2FSAML%26RelayState%3D%3FcourseId%3D91db68a0-581f-467c-84fa-e67430d1c661
Lesson Deeplink:
https://YourADFSDomain.com/adfs/ls/IdpInitiatedSignOn.aspx?RelayState=RPID%3Dhttps%3A%2F%2Fcompanyname.myabsorb.com%2FAccount%2FSAML%26RelayState%3D%3FcourseId%3D91db68a0-581f-467c-84fa-e67430d1c661%2526LessonId%3D4ed77b4f-3cfa-4baf-8b9f-bc92a6713658
0 Comments