OpenIdConnect Single Sign-On

Using OpenIdConnect with Absorb LMS

OpenIdConnect is one of the SSO methods that can be used with Absorb LMS. The other available SSO method is SAML 2.0, which you can read about here: Incoming SAML 2.0

Things to consider before proceeding with an OpenIdConnect configuration with Absorb:

• We do not support user provisioning via this method. If that is a requirement, we recommend using SAML 2.0.
• We only support the Authentication Code Flow as we rely on a JWT for authentication. This is different than Web Server Flow, which will not work with our implementation.
  Our implementation is not compatible with every Identity Provider’s implementation of OpenIdConnect.
• The certificate entered in the Key field in the Absorb SSO Settings must be in x509 format.
• In our experience, implementing OpenIdConnect with Absorb requires more development knowledge on the client’s end than implementing SAML 2.0. We have robust error reporting for SAML 2.0 that we have not implemented for OpenIdConnect.
• At this time, we do not support deep linking as part of the OpenIdConnect SSO.

Troubleshooting Common Errors

If you capture the JWT, it can be decoded at https://jwt.io to verify the information being sent.

500 error: “An unexpected error occurred”

This can occur for a variety of different issues. You can follow the steps below to troubleshoot.

• Confirm that the Issuer URL entered in the Absorb SSO Settings exactly matches the Issuer URL in your /.well-known/openid-configuration. That includes a trailing “/” at the end of the URL.
• Confirm that the signature being used matches the value in Key in the Absorb SSO Settings.
• Confirm the JWT signature type selected in the Absorb SSO Settings matches what’s in your /.well-known/openid-configuration.
• Choose a client secret that is 64 characters (512 bit) in length regardless of the JWT signature type chosen.

“The token response does not contain a valid subject or email claim.”

Confirm that the payload includes a value labeled “Email” or “Emails”.

“No matching Absorb user found” 

Absorb looks at the value sent for Email in the payload and will try to match it to whichever value is selected as the ID Property in Absorb. We recommend selecting Email Address as the ID Property in Absorb. This error indicates that there is no matching active user in Absorb.

OpenIdConnect Single Sign-On with Auth0

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 configuration of SSO using Auth0. For the purposes of this article the Absorb system will act as the Service provider (SP). Your Auth0 account 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 OpenIdConnect Single Sign-On as a feature, however, we do not officially support any specific client-side (IdP) solution. Although Auth0 is known to generally work with our implementation of OpenIdConnect 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 Auth0 instance. This guide is provided to our clients as a convenience only, based on our past experience working with clients who employ Auth0. 

Creating a Client

See https://auth0.com/docs/clients for more information on creating a client.

Choose the appropriate client type

• Native: Used for mobile, desktop, or hybrid apps, than run natively in a device, like Android, Ionic, or iOS.
• Single Page Web Applications: Used for JavaScript front-end apps that run on a browser, such as Angular, jQuery, or React.js. 
• Regular Web Applications: Used for web applications that run on a server. e.g. ASP.NET, Java, or Node.js.
• Non Interactive Clients: Used for server to server applications like CLIs, daemons, or services running on your backend. Typically you would use this option if you have a service that requires access to an API.

Review The Client Settings

• Set an appropriate name for the client.
• Token Endpoint Authentication Method: Post
• Allowed Callback URLs: This is the URL where your Absorb LMS is hosted - please contact us if you do not know this. This URL is usually configured as part of your initial LMS onboarding. e.g. https://companyname.myabsorb.com OR https://some.custom.url
• Allowed Logout URLs: This is the URL Absorb redirects users to when a user logs out of the Absorb system.
• Use Auth0 instead of the IdP to do Single Sign-On: Leave this turned off.

Configure the client to use Auth0 as Identity Provider

1. In the dashboard screen, click the "Clients" link on the left side of the screen.

2. Find the row for your application and click on the "Settings" icon to the right of your application's name. (the round gear icon)

3. Scroll to the bottom of the page and click on “Advanced Settings”.

4. In the expanded window, click on “OAuth” to bring up the OAuth section.

5. For JsonWebToken Signature Algorithm, select either: HS256 or RS256
    The algorithm to choose is dependant on how you would like to sign the JsonWebToken.

6. Use Auth0 instead of IdP to do Single Sign On should be set to Disabled.

7. Click on Endpoints to bring up the Endpoints section.

8. Copy the contents of the "OAuth Authorization URL" field. You will need to provide this to Absorb.

9. Copy the contents of the "OAuth Token URL" field. You will need to provide this to Absorb.

10. For RS256, in the Certificates, copy the contents of the "Signing Certificate" field. You will need to provide this to Absorb.

11. Save changes.

Absorb Setup

Login to the Absorb admin portal as a System Admin and navigate to Portal Settings. 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. 

Click Add and fill in the fields as shown below.

• The Method field: Open Id Connect
• The OpenID Connect authentication protocol method field: Client Secret Basic or Client Secret Post
• The JWT signature type used for the authentication field: HS256 (or as per your IdP setting)
• The Public signing key or certificate from the Authorization Server field: from Auth0, Client settings, Advance Settings, in the Certificates section, copy the contents of the "Signing Certificate" field (the text between the BEGIN and END).  (this is only applicable for RS256)
• The Client Identifier from the Authorization Server field: Client ID (from Auth0)
• The Client Secret from the Authorization Server field: Client Secret (from Auth0)
• The Issuer URL field: https://your-tenant-name-auth0.com (the Domain from Auth0)
• The Authorization Endpoint URL field: https://your-tenant-name-auth0.com/authorize (the OAuth Authorization URL from Auth0)
• The Token Endpoint URL field: https://your-tenant-name-auth0.com/oauth/token (the OAuth Token URL from Auth0)
• The Id Property field: Email Address
• The Automatically Redirect field: ON
• The Assigned Routes field: <<select your route as per your LMS Route Settings>>

Save your changes, and your OpenId Connect SSO configuration and set up is complete.