This article contains information applicable to the refreshed Admin Experience (AE) and previous versions of the Absorb LMS product.

An Introduction to SSO

What is SSO?

What is SSO?

SSO stands for Single Sign-On. It's an authentication method that allows users to log into multiple applications with one set of credentials. Its beauty is in its simplicity; the service authenticates you on one platform, enabling you to transparently login to several internal services without having to log in and out each time.  SSO at a basic level is an agreement between three entities:

  1. Users
  • A User is an individual who needs to access different services.
  • Identity Providers (IdP)
    • An IdP stores the user's information in a database.
    • It may also include additional attributes about the user's identity, like an email address, and pass that information to a Service Provider (SP).
    • IdPs: Microsoft Azure, Auth0, Okta, OneLogin, and Absorb LMS.
  • Service Providers (SP)
    • The term "Service Provider" or SP is a formal way of identifying an application or service that Users need to authenticate (sign-in) to access.
    • The definition of an SP isn't limited to websites or web applications.  For example, to use some organizations' Wi-Fi networks, you must use the same username/password combination as your company email. In this scenario, the organization's Wi-Fi is an SP (and you authenticate by using SSO!)
    • SPs: Absorb LMS, Dayforce, Jira, and Confluence. 
    Example: Not Using SSO Example: Using SSO
    Example-No-SSO.png Example-With-SSO.png
    When not using SSO, the User must remember the username/password combination for each Service Provider (SP). When using SSO, the User only needs to remember a single username/password combination: that of their Identity Provider (IdP).

    Once authenticated into their IdP, the User is  "signed-in" to all of their SPs.

     

    Benefits of Using SSO

    Benefits of Using SSO

    There are a variety of use cases for SSO. Among them, some of the common ones are:

    • Simplification: With SSO, Users only need to remember a single username/password combination for their Identity Provider (IdP). Once authenticated with the IdP, the User is automatically logged in to all of their organization's Service Providers (SP).
    • Access Provisioning: Service Providers (SP) that offer to provision (e.g. Absorb!) can help automate new hire accounts for all of the organization's other services.

      Example: Virginia has been hired by Robotech.  Robotech uses the following Service Providers (SP): Absorb LMS, Dayforce, and Office635 email accounts.
      • If Robotech doesn't use SSO, new hire accounts will need to be manually created by a member of Robortech's staff (usually HR or IT).
      • If Robotech uses SSO, Virginia will only need to have an account with Robotech's Identity Provider (IdP).  When Virginia first attempts to access Absorb LMS through SSO, provisioning will automatically create within Absorb LMS using the fields provided by the configuration of the SSO provisioning.
         
    • Access Deprovisioning: Similarly, to the above point, if an employee leaves a company, the company only needs to disable their account in one location, the Identity Provider (IdP), and the employee will automatically no longer have access to any of the service providers behind it.

      Example:
      Jane is retiring from Robotech. Once she's retired, the company understandably doesn't want her accessing any of its internal services. All the company has to do is disable Jane's account in their identity provider. Since all of Robotech's service providers rely on Jane signing into the identity provider first, and because Jane can no longer sign in to the identity provider, Jane won't be able to access any of the service providers.
    How Does SSO Work?

    How does SSO work?

    SSO works by transferring the user’s identity from one place (the Identity Provider (IdP)) to another (the Service Provider (SP)). There are a few different ways for the user's identity to be transferred, using communication methods known as "protocols".

    The most commonly used & supported SSO protocol is the Security Assertion Markup Language 2.0 (SAML for short). When a user logs into a SAML-enabled application, the service provider requests authorization from the appropriate identity provider. The identity provider authenticates the user's credentials and then passes the authorization for the user to the service provider and the user is now able to use the application.

    SSO Simplified

    1. User attempts to access a service provider (e.g., Absorb LMS), either by clicking on a link, visiting a bookmark, or some other way.
    2. The service provider sends a request over to the identity provider: "Who is this person?"
    3. The user logs into the identity provider, which tells the identity provider who they are.
    4. The identity provider sends a response to the service provider: "This is jane.donut, sign them in please."
    5. The service provider signs the user into the jane.donut account.

    The above must be done in a secure way. As such, our requests and responses are with certificates.  Our service provider wants to make sure that the identity provider it's talking to is the identity provider it should be talking to and not some other (potentially malicious) entity posing as your organization.

    Likewise, the identity provider also wants to be sure it's sending information to the correct service provider. Without going into too much detail, these certificates are like a secret handshake used to verify that who the LMS is communicating is correct and help ensure the safety of your data.

     

    SSO Protocols

    SSO Protocols

    There are two major SSO protocols supported by Absorb. SAML (short for Security Assertion Markup Language) and OpenID Connect. Absorb supports both methods and a time of writing, SAML is currently the most common setup used for SSO. Unless your organization is just starting to investigate SSO and is working to decide what’s best, it is likely that the Protocol you will be using has already been determined.

    1. SAML: Initially published in 2001, SAML is an XML-based Markup Language and can be configured as either Identity Provider Initiated, or Service Provider Initiated (Covered in the next section).
    2. OpenID Connect: Published in 2014 OpenID Connect is the 3rd iteration of the OpenID protocol after OpenID and OpenID 2.0. OpenID Connect makes use of RESTful API & JSON

    SAML SSO

    SAML Basic Workflows

    SAML Basic Workflows

    There are two main types of SAML SSO: Identity Provider Initiated (IdP) and Service Provider Initiated (SP), depending on which system (the IdP or SP) activates the process. We recommend using Service Provider Initiated if possible as several limitations may affect your SSO if you use Identity Provider Initiated. The critical difference between IdP and SP is where the whole process starts:

    • With SP Initiated, the user starts by attempting to access the Service Provider: Absorb. Then Absorb (the SP) sends the IdP a request containing some basic information about what the user is asking to do.
    • With IdP, the user starts on their IdP and clicks a link in their identity provider to access Absorb. 

    Note: When users have a direct URL to your organization's Absorb LMS portal (e.g., Company.myabsorb.com), an IdP SSO will not redirect to the SSO login page if the Automatic Redirect function is enabled.

    Request VS Response

    SAML SSO makes extensive use of two specific call types: Requests or Responses. These can be defined as follows:

    • Request: A request is sent by the SP to the IdP in the Service Provider Initiated flow to request to authenticate the user and redirect them afterward. 
    • Response: A response (also called a SAML Assertation) contains user authorization and other details provided by the IdP; and will send Signature, Subject, and Attributes.

    Inbound VS Outbound

    SAML SSO has two possible settings when using Service Provider Initiated (SP): Inbound and Outbound. As implied by the names, this relates to the direction of the SSO. 

    • Inbound SSO: An Inbound SSO refers to the user coming into Absorb via authentication from an IdP. 
    • Outbound SSO: With Outbound SSO, the SSO connection initiates when the user is moving outside of Absorb, often via a tile set up on the dashboard of the LMS, in tandem with settings in the SSO Settings page. 

    Unless there is a use case where clients want their users to access materials outside of Absorb without authenticating (using Outbound SSO), most clients will use Inbound SSO.

    Identity Provider Initiated (Inbound) Workflow

    IdP (Inbound)

    With IdP (Inbound), the user starts on their identity provider and clicks a link in their identity provider to access Absorb (via a "my apps" page or something similar).

    (Optional) Identity Provider Initiated SSO requires the user to start at their IdP. To facilitate this, the Automatically Redirect option must be enabled within the Absorb LMS > Portal Settings. With this feature active, users are automatically redirected to their IdP when they attempt to access Absorb.

    1. User logs in via their IdP login page.
    2. The IdP sends a request to a unique Absorb URL (called the ACS URL; more on this later)
      • This URL is both client-specific (to the Absorb route) and interface-specific. 
    3. Absorb then confirms that the IdP is who it claims to be by un-encrypting the request signature/certificate using the provided certificate key.
    4. Absorb checks the NameID in the SAML response and matches it against Absorb using the Id Property.
      • For example, if the NameID is Absorb.Test and the Id Property is Username, Absorb is checking for a username of Absorb.Test
    5. If the user exists, matching the Id Property, the user is logged into Absorb and can begin their learning journey.
    Service Provider Initiated (Inbound) Workflow

    SP (Inbound)

    With SP (Inbound), the user starts by attempting to access Absorb LMS; Absorb sends the IdP a request containing some basic information about what the user is asking to do.

    1. The user navigates to a resource in their Absorb LMS instance (one that requires a login) and is redirected to their IdP along with a SAML request (see example below)
    2. User logs in via their identity provider login page if necessary.
    3. The identity provider sends a response to a unique Absorb URL (called the ACS URL; more on this later)
      • This URL is both client-specific (to the Absorb route) and interface-specific. 
    4. Absorb confirms that the identity provider is genuine per the information on the signature provided by the IdP
    5. Absorb checks the NameID in the SAML response and matches it against Absorb using the Id Property.
      • For example, if the NameID is Absorb.Test and the Id Property is Username, Absorb is checking for a username of Absorb.Test
    6. If the user exists, matching the Id Property, the user is logged into Absorb and can begin their learning journey.
    7. If the user doesn't exist, Absorb will display an error.
    Direct Login on Absorb with an Active SSO

    SP (Outbound)

    Additionally, it is possible to set a unique password on Absorb while SSO is in use (e.g., for clients who aren't using SSO and their learners log in directly via Absorb). However, this functionality will be different if using Service Provider Initiated or Identity Provider Initiated.

    • Service Provider InitiatedThe route(s) associated with the SSO will automatically redirect to the SSO login page if enabled. In this case, a user would be able to log in using a route not associated with the SSO or through the Admin route (for the SSO) if the user has admin access to the LMS. (e.g., Company.myabsorb.com/admin
    • Identity Provider InitiatedWhen the SSO settings have the Automatic Redirect option enabled, the user can log in on the login page for the LMS, provided they have the correct URL.
      If Automatic Redirect is enabled in the SSO settings, this will cause the SSO to redirect the user to the SSO login page, similar to when using Service Provider Initiated. In this case, they would need to use either a route not associated with the SSO or log in through the Admin route if the user has admin access to the LMS. (e.g., Company.myabsorb.com/admin

    Service Provider Initiated Outbound Workflow

    1. User logs into Absorb.
    2. User accesses a resource that includes an SSO link to an external protected resource, e.g., a dashboard tile or, more commonly, a lesson in a course such as an AICC link (e.g. LinkedIn Learning)
    3. The user is redirected to the service provider URL.
    4. The service provider sends a SAML request to Absorb.
    5. Absorb confirms that the identity provider is who it claims to be by un-encrypting the request signature/certificate using the provided certificate key.
    6. Absorb sends a SAML response to the service provider (as above)
    7. The service provider verifies the response using Absorb's metadata.
    8. If the user exists matching the Id Property, that user is logged into the service provider.
    Provisioning SAML

    Provisioning SAML

    User provisioning (also known as Just in Time, or JIT provisioning) is when a user account is created within a service provider system when the user attempts to log in. 

    This process follows the same incoming workflows as above. Still, when a matching user is not found, Absorb will try to create the user using attribute information in the SAML response rather than displaying an error.

    Absorb currently only supports provisioning with SAML SSO. 

    Requests and Responses (SAML)

    Requests and Responses (SAML)

    Request

    A request is sent by the Service Provider (SP) to the Identity Provider (IdP) in the Service Provider Initiated flow to request that a user be authenticated. It asks the Idp to authenticate the user, and where to send the user afterward.

    An Assertion Consumer Service URL (ACS URL) tells the Idp where to send its response once the user has logged in. It's a special URL that is ready for SAML responses and knows what to do with them. In Absorb, ACS URLs are route-specific.

    Click here to download a SAML Visual Workflow Comparison.

    Response

    A response contains information from the identity provider with the user's authorization (this is also called a "SAML Assertion"). It's made up of a few key parts:

    • Signature: Includes the signature value that must be unencrypted, as well as the certificate key and the encryption algorithm used.
    • Subject: Basic information on who the SAML response is about (e.g., their username).
    • Attributes: Additional information about the user. In Absorb, attributes are only used for user provisioning.

    Click here to download an example SAML Response

    Terminology

    Terminology

    Some of the below terminologies is SAML specific, but similar concepts exist in all types of SSO (e.g., Open Id)

    Term Definition
    Key/Certificate The key is used to confirm that both parties are who they say they are, which helps protect the security of the user and their data. The certificate in Absorb is expected to be in X.509 (base 64) format.
    Request The part of the SSO workflow where the service provider asks the identity provider to start the authentication process.
    Response The part of the SSO workflow where the identity provider sends the service provider information on whether the user is allowed to log in. 
    Assertion Consumer Service (ACS) URL An endpoint on the service provider where the identity provider will redirect to with its authentication response.
    POST A method of sending data over HTTP to another server.
    Signature Type The type of encryption used for communication (typically SHA256 - Secure Hash Algorithm)
    Id Property The property used to identify the user. For example, if the Id Property is username, Absorb is expecting to receive a username in responses.
    Incoming Single Sign-On User is being signed into Absorb from another site (note that this will often be reversed if the other party is talking!)
    Outgoing Single Sign-On User is being signed into another site from Absorb (note that this will often be reversed if the other party is talking!)
    SAML Trace(r) An application or browser add-on that allows you to view a SAML request or response. 
    Identify Provider (IdP) This is the website, service, etc. that authenticates the user. 
    Service Provider (SP) This is the website, service, etc. providing the resource that the user wishes to access.
    Security Assertion Markup Language (SAML) Most commonly used standard for SSO.

    SSO Considerations

    Considerations
    1. What Type of SSO does your organization want?
    • Identity Provider Initiated 
      • The learner starts at (or is redirected to) their identity provider and after authentication is sent to Absorb.
      • If possible, it’s best to use Service Provider Initiated As it will provide the smoothest experience.
    • Service Provider Initiated (This is the mode we strongly recommend)
      • The learner starts at Absorb and Absorb sends a request to their identity provider.
      • This is the mode that must be used for using SSO with the mobile app.
      • This mode is also what must be used for standard deep links to work.
    • Service Provider Initiated Outbound
      • The learner starts at Absorb and is sent somewhere else.

    Absorb is the identity provider in this case.

    mceclip0.png

    2. Which protocol is your organization going to use?
    • SAML 2.0
      • This is the only protocol with which Absorb supports user provisioning.
    • OpenId Connect
      • Important distinction: Open Id Connect is not the same as Open Id / Open Id 2.0.

    Absorb only supports Open Id Connect.

     

    SAML-OIC-Comparison.png

     

    3. Which ID Property (NameID) is your organization going to use?

    Your organization will need to decide how the identity provider will identify the user to the service provider. Whichever method you use needs to be present on BOTH platforms. 

    At the time of writing, Absorb supports the following Id Property options on SAML; however, Open Id Connect can only use Email Address:

    • ID (User's GUID)
    • Username
    • Email Address
    • External Id
    • Employee Number

    Note: The ID Property must be populated for all users who will be using the SSO. This value is used to match the field in the LMS to the attribute provided by the SSO. Often clients will choose to use the External ID field from Absorb, as an LMS admin cannot edit this field through the Admin interface.

    Absorb ID refers to the GUID (Global Unique Identification) set generated by the system when a user's account is created. Because of this, this is not recommendable for use with User Provisioning.

    ID-Property.png

     

    SAML

    What are the Identity Provider and Service Providers' Certificates?

    You will need two certificates. The identity provider and service provider each have their own certificate and you will need to exchange them with each other.

    • Absorb's certificate can be found in our Metadata. It's the encoded string between the <ds:X509Certificate> and </ds:X509Certificate> tags.
      • Note: SOME identity providers, such as Okta, won't require Absorb's certificate.
    • The certificate on your identity provider (or service provider, if your organization is using Service Provider Initiated outbound) must be provided by their end.

    Do you want User Provisioning?

    Do you want Absorb to create users if they don't exist? If so, bear in mind that you will need to set up their identity provider to send the required attributes to Absorb.

    Learn more: More details are in Incoming SAML 2.0 SSO Account Provisioning article.

    Which Portal Routes do you want to be associated with the SSO?

    If your portal only has one route this is simple, but if your portal has multiple then you can decide which URLs you want to have associated with this SSO configuration. Other routes can be attributed to other SSO configurations (if you have any), or you can keep them unassociated.

    Note: Routes that aren't associated with an SSO configuration will work as though the portal does not have SSO set up for those specific routes (i.e., users will see the regular Absorb login screen/dashboard).

    Configure your Identity Provider

    You or your IT will need to configure your identity provider. Absorb does not directly assist with this, but we do have a few articles on how to do so with popular identity providers (A list of these articles is available at the end of this article),

    You’ll need your ACS URL, Absorb's Certificate, and know which user property (NameID) you want to send over to Absorb (e.g., if you want to use email as the Id property, you'll need to know which field in your identity provider contains their users' emails).

    Configure Absorb

    You will need to navigate to Portal Settings > Manage SSO Settings > Add.

    • Name: Something descriptive. This name is only visible to portal admins.
    • The Key field should contain the full certificate from your SSO's identity provider.
      • Remove the entire "BEGIN CERTIFICATE" line if it exists.
      • Remove the entire "END CERTIFICATE" line if it exists.
      • Remove all line breaks (you should be left with a single line of encoded text.)
      • Copy this information into the Key field in Absorb.
    • Mode: Select the appropriate SSO type (Identity provider-initiated, service provider-initiated, service provider-initiated outbound).
    • Id Property: The NameID you want to use.
    • Signature Type: This tells Absorb how the identity provider has encrypted their key. More often than not this can be left as-is unless your identity provider specifies otherwise.
    • (Inbound only) Login URL: The login URL from above.
    • (Inbound only) Automatically Redirect
      • If enabled, unauthenticated users will be redirected to the identity provider's login screen as soon as they land on your portal's Absorb URL.
      • If disabled, unauthenticated users will see the public dashboard.
    • (Inbound only) Assigned Routes: Which portal routes do you want to be associated with SSO?
    • (Inbound only) Allow User Provisioning: Whether or not you want user provisioning enabled.
      • You will need to configure your identity provider to send user attributes if this is enabled or it won't work.
    • (Outbound only) Assertion Consumer Service Url: Generally, this is left blank because your service provider will include it in the request it sends to Absorb. If that's not the case, you can hard code an ACS URL here.
    • (Outbound only) Include User Data: If set to ON, Absorb will include more data about the user than just the ID Property in its response.
    • Logout URL: The URL the user should be taken to if they log out of Absorb (If blank, it will take the user to the login page  

     

     

    OpenID Connect

    What are the identity provider's properties?

    Your identity provider will have to provide you with the following details:

    • OpenID Connect authentication protocol method.
      • JWT signature type
      • Client Identifier (sometimes called a client id or application id)
      • Client Secret
      • Issuer URL
      • Authorization Endpoint URL
      • Token Endpoint URL
    • The Identity Provider properties will tend to be provided within the Identity provider’s administrator console. If not readily available, please consult your Identity provider’s documentation to confirm where to find this information.

    What are your Issuer & Endpoint URLs?

    • Issuer URL: the base URL for the OpenID endpoint
    • Authorization Endpoint URL: uses the OAuth Authorization URL
    • Token Endpoint URL Uses the OAuth Token URL
    • Will you be using an HS256 or RS256 type signature?
    • HS256: This uses the Client Identifier and the Client Secret from the Authorization Server; the Public signing key field or certificate field will not be available to you.
    • RS256:   This uses the Client Identifier and the Client Secret, and the Public signing key field or certificate field from the Authorization Server.
    • These cannot be mixed & matched and must match the configuration on your Open Id Connect SSO.

    Which Portal Routes do you want to be associated with the SSO?

    N/A

    Configure your Identity Provider

    Unlike SAML, in Open Id Connect routes are associated with the SSO configuration in the Allowed Callback URLs. Using the:

    • https://domain.myabsorb.com
    • https://domain.myabsorb.com/api/rest/v2/authentication/openIdConnect

    Formats for each assigned route.

    Configure Absorb

     You will need to navigate to Portal Settings > Manage SSO Settings > Add.

    • Name: Something descriptive. This name is only visible to portal admins.
    • OpenID Connect authentication flow mode.
      • Currently, only Authorization Code is available
    • OpenID Connect authentication protocol method.
      • Client Secret Basic
      • Client Secret Post
    • JWT signature type used for the authentication: The encryption method to be used for the Signing key on the SSO is either:
      • HS256 (HMAC with SHA-256)
      • RS256 (RSA Signature with SHA-256)
      • This must match the configuration in your OpenID setup.
    • Public signing key or certificate from the Authorization Server: field should contain the full certificate from your SSO's identity provider. NOTE: This must be in x509 format. Other certificate formats will not work for Absorb.
        • Remove the entire "BEGIN CERTIFICATE" line if it exists.
          • Remove the entire "END CERTIFICATE" line if it exists.
          • Remove all line breaks (you should be left with a single line of encoded text.)
          • Copy this information into the Public signing key or certificate from the Authorization Server field in Absorb.
    • Client Identifier from the Authorization Server: The Client ID from the IDP
    • Client Secret from the Authorization Server: The Client Secret from the IDP
    • Issuer URL: The IssuerURL from above (Must Match)
    • Authorization Endpoint URL: The Authorization Endpoint URL from above
    • Token Endpoint URL: The Token Endpoint URL from above
    • Id Property: Unlike SAML, this must be configured for email only.
    • Logout URL: The URL the user should be taken to if they log out of Absorb (If blank, it will take the user to the login page
    • Automatically Redirect: If enabled, unauthenticated users will be redirected to the identity provider's login screen as soon as they land on your portal URL.
    • If disabled, unauthenticated users will see the public dashboard.
    • Assigned Routes: Which portal routes do you want to be associated with your SSO? Must match Allowed Callback URLs in the OpenID configuration.
    Metadata

    Metadata

    Metadata is used to transfer information about the parties involved in the SSO connection (both the Idp and PS). Metadata is often provided as an XML file, but it can also be plain text formatted like XML. Typically, metadata is only needed for Outgoing Service Provider Initiated SSO because:

    • Absorb does not have a mechanism to upload metadata.
    • The system only asks for fields the LMS will require. (for the identity provider, these would be the certificate key, signature type, and login URL)
    • Most information (like URLs) is available in our documentation.
    • 3rd party applications may require the metadata in XML format, which is why we provide this for Outgoing Service Provider Initiated

    Click here to download an example of Absorb Metadata.

    Troubleshooting SAML SSO

    Troubleshooting

    When you receive an error message, perform a SAML trace to review the associated issue.  Many times you will be able to resolve these on your own without Absorb Support. 

    Please note, these instructions are only for those using SAML SSO.  Click here to download an example of Outgoing SAML SSO. 

    • The Certificate Key - This can be found in the <X509Certificate> tag.
      • For incoming SSO this value should be an exact match to the key value set in your Absorb LMS portal.
      • For outgoing SSO it should be an exact match to the key value set in your 3rd party system (because it's coming from Absorb). If the key does not match exactly, it can prevent SSO from working.
    • The NameID - This can be found in the subject in the <NameID> tag in a SAML trace. This property should match an existing user in Absorb based on the ID Property set in Absorb SSO settings. If the NameID value doesn’t match the ID Property in Absorb, the user will be unable to log in.

    • Signature type - This can be found in the <SignatureMethod> Algorithm. Failures due to a mismatch on the Signature type are rare, however, if an error is caused due to the signature type failing to match, this will tend to result in an “invalid Signature” error.

     SAML Tracers

    Browser Information
    Chrome

    SAML Chrome Panel. This shows up in Developer Tools.

    Note: The Dev Tools page needs to be open before you start the SSO process.

    Firefox SAML Tracer
    Fiddler Alternative: Some clients use Fiddler to troubleshoot SAML issues. Instructions for Fiddler are available here.

     

     


    Was this article helpful?
    0 out of 0 found this helpful