When setting up Single Sign-On (SSO) for your organization, there are several decisions that you want to make ahead of the implementation. Making these decisions in advance will help your team to prepare and avoid roadblocks during the process.

This article outlines some considerations that your team should take into account when exploring SSO options for your organization, including the type of SSO, protocol choice, metadata, and troubleshooting some common issues.

Considerations

There are several questions you will want to ask before implementing SSO at your organization. These questions can help direct your implementation and reduce time during the set up process. This section addresses some of these questions:

What Type of SSO Does Your Organization Want?

There are three options to choose from:

• Identity Provider Initiated
  • The Learner starts at (or is redirected to) their Identity Provider after authentication is sent to Absorb.
• Service Provider Initiated (Recommended)
  • The Learner starts at Absorb, who sends a request to their Identity Provider.
  • This mode must be used for SSO with the Mobile App. More information can be found in the SSO & The Absorb Learning Mobile App article. 
  • This mode is also required for standard deep links to work.
  • We strongly recommend using this method to provide for the smoothest SSO experience.
• Service Provider Initiated Outbound
  • The Learner starts at Absorb and is sent somewhere else.

The chart below shows what type of SSO is best suited to each scenario, where Absorb is the Identity Provider in this case:

Which Protocol Is Your Organization Going to Use?

There are two Protocol options when setting up SSO with Absorb:

• SAML 2.0
  • Security Assertion Markup Language (SAML) 2.0 supports User Provisioning.
  • You can read more about Incoming SAML SSO in the Incoming SAML 2.0 Single Sign-On article.
• OpenID Connect
  • Note that OpenID Connect is not the same as Open Id / Open Id 2.0.
  • OpenID Connect also supports User Provisioning when RS256 and Use Dynamic Keys are enabled.
  • You can read more about OpenID Connect SSO in the OpenID Connect Single Sign-On article.

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, OpenID Connect can only use Email Address:

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

Protocol Configuration

Each Protocol has separate conditions that should be considered before you decide on which one to implement. In this section we will go over each of the Protocols, specific considerations for each, and how to configure them.

SAML

This section discusses considerations specific to the SAML Protocol.

What Are the Identity Provider and Service Provider 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, like 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, keep in mind that you will need to set up their Identity Provider to send the required attributes to Absorb.

• More details can be found in our Incoming SAML 2.0 SSO Account Provisioning article.

Which Portal Routes Do You Want to Be Associated with the SSO?

As part of the SSO configuration, you will need to decide which Portal Routes are associated with your SSO. If your Portal only has one Route, this makes the decision simple. However, if your Portal has multiple Routes, then you can decide which URLs you want to associate 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 department will need to configure your Identity Provider. Absorb does not directly assist with this, but you can read more about Identity Provider configuration in the articles linked at the Related Articles section.

You'll need your Assertion Consumer Service (ACS) URL, Absorb's certificate, and the User Property (NameID) you want to send over to Absorb. For example, if you want to use email as the ID Property, you'll need to know which field contains Users' emails in your Identity Provider.

The ACS URL follows this format, where company.myabsorb.com is replaced with your Portal URL:

https://company.myabsorb.com/api/rest/v2/authentication/saml 

Configure Absorb

In the Admin Experience, follow these steps to configure your SSO:

1. Log in as a System Admin and navigate to Client Settings.
2. Click the SSO card.
3. Click Add SSO Configuration to create a new SSO configuration.
4. Complete the Connection Type step, entering a descriptive name for the connection. This name is only visible to Portal Admins.
5. Complete the Configuration step using the field descriptions in the table below. Note that some fields are only available for Inbound or Outbound SSO types.
6. Complete the Access step to assign Portal Routes.
7. Click Save.

OpenID Connect

In this section we will go over considerations specific to the OpenID Connect (OIDC) Protocol.

OpenID Connect Limitations

Before implementing OpenID Connect, consider the following limitations of this protocol:

• Manager Experience is not supported for OIDC-authenticated Users.
• Administrative roles cannot be assigned through OIDC. Admin access must be configured separately within Absorb.
• Deep linking is not supported as part of OIDC.

What Are the Identity Provider's Properties?

Your Identity Provider will need to provide you with the following details:

• JSON Web Token (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 typically 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 and Endpoint URLs?

In OpenID Connect, these URLs are as follows:

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

Both signatures have specific considerations:

• 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. Dynamic key retrieval and User Provisioning are not available with this signature type.
• RS256: This uses the Client Identifier and the Client Secret, and the Public signing key field or certificate field from the Authorization Server. RS256 also supports Use Dynamic Keys, which enables Absorb to retrieve signing keys from your Identity Provider automatically and is required to enable User Provisioning.
• These cannot be mixed and matched and must match the configuration on your OpenID Connect SSO.

Configure Your Identity Provider

Unlike SAML, in OpenID Connect routes are associated with the SSO configuration in the Allowed Callback URLs. Use the following formats for each assigned route:

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

Configure Absorb

In the Admin Experience, follow these steps to configure your SSO:

1. Log in as a System Admin and navigate to Client Settings.
2. Click the SSO card.
3. Click Add SSO Configuration.
4. Select OpenID Connect as the method.
5. Complete the available fields using the descriptions in the table below.

Metadata

Metadata transfers information about the parties involved in the SSO connection (both the Identity Provider and Service Provider). Metadata is often provided as an XML file, but it can also be plain text formatted like XML.

Typically, only Service Provider Initiated Outbound SSO requires metadata. This is due to the following:

• 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.
• Third-party applications may require the metadata in XML format, which is why Absorb provides this for Service Provider Initiated Outbound.

Download an example of Absorb Metadata.

Troubleshooting

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

Please note, these instructions are only for those using SAML SSO. 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 impact SSO functionality.
• 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

There are different SAML Tracers available for use. Some are specific to certain browsers.

You can also use the Fiddler debugging tool to troubleshoot SAML issues. Note that the link redirects to third-party documentation for Fiddler. 

Related Articles

Explore the articles below for more information on SSO topics:

• Incoming SAML 2.0 Single Sign-On
• Outgoing SAML 2.0 Single Sign-On
• Incoming SAML 2.0 SSO Account Provisioning
• OpenID Connect Single Sign-On
• Route Level Single Sign-On
• Implementing a Custom SAML and User Provisioning Solution