Docebo for OpenID Connect

Introduction

OpenID Connect (opens in a new tab) is a simple identity layer on top of the OAuth 2.0 protocol. It allows you to verify the identity of users based on the authentication performed by an Authorization Server, and to obtain basic profile information about them in an interoperable way. Docebo supports the OpenID Connect Authorization Code flow, which is one of the available flows for authentication. Please refer to the OpenID Connect technical documentation (link opens in a new tab) for further information.

By activating the OpenID Connect app in your Docebo platform, users will be able to log into their Docebo platforms using the credentials from active sessions of other web platforms.  When the app is active, users can press the OpenID Connect icon in the Docebo login page to connect to the platform with the credentials of other web platforms, and will also be allowed to log into the Docebo platform from the OpenID Connect dashboard, by pressing the Docebo platform icon. If a user requesting to login does not exist in Docebo yet, he or she will be automatically created at the first login.

This article will give you a step-by-step process of how to activate and configure the app. Please note that the integration with OpenID Connect is available for Docebo’s Extended Enterprise App.

Please note: When using OpenID Connect, you can integrate a single Identity Provider per platform domain. If you need to integrate other identity providers for the same domain, please use another protocol.

The Go.Learn mobile app supports OpenID Connect single-sign on provided that the identity provider allows query parameters such as ?device=mobile to be appended during authentication. For more information see the chapter Configuring the OpenID Connect app.

Best practice: When an SSO integration and a custom domain are set up at the same time, it is strongly suggested to configure the custom domain in Domain Management first. The endpoint URLs needed for the SSO integration are dependent on the URL of the platform.

Activating the OpenID Connect app

Activate the OpenID Connect app as described in the Managing Apps & Features article of the Knowledge Base. The app is listed in the Single Sign On tab.

Once it’s activated, you can begin the configuration. Please refer to the section below to learn more.

Configuring the OpenID Connect app

To begin the configuration for this app, log into your platform as Superadmin and access the Navigation menu. Then, find the OpenID Connect section in the Add-ons and integrations (jigsaw icon). You will be redirected to the OpenID Connect Settings page. 

The URLs listed in the Platform URLs section are automatically generated by your platform, and must be passed to your Identity Provider for a proper configuration of the Docebo platform in their platforms:

Login URL

3rd-party application login page for federated authentication using OpenID Connect

Logout URL

Logout URL used to log the current user out of the 3rd-party application

Please note: If you want to use OpenID Connect SSO on your Go.Learn or branded mobile app, you need to add the golearn://sso_logout URL to the list of sign-out redirect URIs (also called logout redirect URIs or callback URLs) on the Identity Provider configuration page.

Code URL

Redirect URL of the 3rd-party application for OpenID Connect code responses.

Please note: If you want to use OpenID Connect SSO on your Go.Learn or branded mobile app, you need to add the ?device=mobile parameter at the end of the code URL when copy-pasting the code URL from Docebo to the Identity Provider configuration page. Not all Identity Providers allow query parameters to be appended to authentication requests (example: Azure AD B2C).

The OpenID Client section must be filled in with the details of the Identity Provider you are integrating. Copy and paste this data from the provider into this section in your Docebo platform. Check the technical documentation of your identity provider for information on how to obtain this data. If your Identity Provider is OKTA, OneLogin, Salesforce, Microsoft Entra ID, Microsoft Azure AD B2C or Ping Identity, you’ll find Configuration Examples listed in the article OpenID Connect configuration examples.

Issuer

The authorization server’s complete URL

Client ID

The client ID of the client requesting to access the token

Client Secret

This client secret is used in conjunction with the Client ID to authenticate the client application

Metadata URL

Returns OpenID Connect metadata related to the specified authorization server. The Metadata URL provides all the data configurable in the second section of the OpenID Connect configuration page.

Use the Auth Type section to select whether to activate the Basic Auth or the Query String Authentication type, depending on the Identity Provider you are using. The Basic Auth type is the default selection because it’s the most commonly used. Please refer to the documentation of your Identity Provider to retrieve this information.

Press Continue to activate the second slot of parameters, and proceed with the configuration. The upcoming options are self-populated by the Metadata URL.

• You can press Reset at any time to start the configuration from scratch. In this case, after you complete the first slot of parameters and press Continue, also press Save changes at the end to refresh the page and properly retrieve the options from the Metadata URL.

Username attribute

When you implement single sign-on (SSO) through an identity provider, the decision about whether a user logging in via SSO already exists within the platform typically depends on a unique identifier field received from the identity provider. 

From the Username attribute drop-down list, select the field you want to use for this purpose:

• The list is auto-populated with the fields available from your identity provider. 
• When making your selection, make sure that the selected field is populated for all your users in the identity provider. 
• The selected field should also be unique. For example, if you select family_name, you must be sure that none of your users have the same family name in the identity provider. 
• For example, you can use  email as the Username attribute, provided all your users have distinct emails on the provider side. 

The identity provider field you select in Username attribute will be matched to the Username field on the platform. This means that:
- If the two fields match, the user authenticating via SSO is considered to already exist in the platform, and will be logged in to that account.
- If no matching Username is found in the platform, then the SSO user does not yet exist in the platform, but can be automatically created if you configure User provisioning.

Fields/claims are by default retrieved from the IdP access token. Select the option Retrieve claims through the Userinfo endpoint only if your implementation retrieves all claims through that endpoint instead.

Scope

The Scope list options are automatically populated with fields retrieved from the identity provider via the Metadata URL entered in the OpenID client section. The options you see here depend on the identity provider's configuration. 

Scopes help the identity provider decide what user information (claims) should be included in the ID token or available through the /userinfo endpoint. Select the check boxes corresponding to the types of user data you want to retrieve. The selection you make here determines what claims will be available in the User provisioning section. Please note that Email and Profile are required scopes and must always be selected.

Token exchange method

Use this setting to define how the system sends the JWT data request to the Identity Provider. By default, Docebo sends requests via the URL using GET parameters. When using the POST option, Docebo sends requests via the URL using POST parameters, adding them to the BODY of the call.

The GET option is simpler and sends the data through the URL, while the POST option is more complex, but uses a more effective encryption method.

Please Note: This option is set to GET by default. When using this setting, make sure you have properly configured your Identity Provider according to the selected option.

Both the GET and the POST requests send the following data for the authorization code authentication type:

Code

The Code value exchanged by the OpenID standard, when using the authorization code authentication type

Redirect URI

The URI where Docebo sends the JTW.

When using the basic auth authentication type, the following data is also sent:

• Client ID
• Client Secret

State parameter validation 

It is recommended to set the option to Enforce and validate state parameter, as this provides increased security. Deselect this option only if your identity provider is not configured for sending or validating the state parameter.

Certification rotation

When the Certification Rotation option is enabled, the Docebo platform will retrieve the key that is valid at the time of the request from an URL defined by the OpenID Connect standard. The Identity Provider will auto-enable the option to refresh the certification autonomously. This is part of the standard relation, and it is either auto-flagged or not.

If the Identity Provider does not support the certification rotation, but this option is enabled, an error message will be shown.

SSO behavior

The SSO behavior can be configured in two different ways. Define whether you want to show the standard Docebo platform login page, or if you want to automatically redirect the users to the Identity Provider dashboard. When the first option is flagged, define whether you want to show the SSO button on your platform’s login page.

When selecting the option for an Automatic redirect to Identity Provider, you can set a specific logout landing page when your users log out of the platform instead of keeping the standard logout page. Use the text box to type in the URL of the logout landing page.

For more information see the article General guidance for SSO configuration > SSO behavior.

Logout behavior

The Logout Behavior section allows you to configure if users will be automatically logged out from the Identity Provider when they log out from the Docebo platform. 

As an additional option, you can select a custom third-party logout endpoint, able to receive the logout message via GET in order to complete the Single LogOut; this option is supported by a few Identity Providers.

In this section you can also activate the switch to not send id_token_hint. Please note that Docebo does not recommend using this option. 

For more information see the article  General guidance for SSO configuration > Logout behavior.

User provisioning

User provisioning allows you to automatically create a new user in the platform if the SSO authentication is valid but that user does not yet exist in the platform. It also allows you to automatically update the details of a user in the platform based on the corresponding information in the SSO identity provider. 

Tip: A user is considered to already exist in the platform if their Username matches the identity provider field you set as the Username attribute. See the chapter Username attribute.

Enable creation of provisioned users:

To begin, flag the Enable option. With provisioning enabled, a user logging in via SSO who does not yet exist in the platform will be created on the fly, with platform Username = the provider field set in Username attribute.  

Note on default branch placement: For SSO on the root platform, newly created users will be placed in the root branch. For SSO on an extended enterprise client, newly created users will be placed in the branch associated with the client.

Add more provisioned fields: 

In addition to the Username, you may want to populate other details of a provisioned user using the information retrieved from the identity provider. 

You configure this in the Add fields section. Here, the Select field drop-down list shows all the user fields and user additional fields that are configured in the platform. 

• From this list, select the desired field, so that it appears under the Platform fields heading. 
• Then from the drop-down list alongside the newly added field, select the matching value from the identity provider that you want to use for that field.  It will appear under the OpenID connect claim heading. 

Repeat the preceding two steps for all the fields you want to provision. Note that each platform field and identity provider field can be used only once.  You cannot match multiple platform fields to the same OIDC claim, or vice versa. 

Tip: If in the platform Advanced settings > Self-registration you flagged the option First and last name are required to register, ensure that you include these fields in the Add fields section, so that the provisioned users can be created. 

Similarly, if you have set some user additional fields as mandatory in the platform, make sure these are mapped here so they can be populated, as otherwise the user cannot be correctly created. For more information see the chapter Supported additional field types for provisioning.

Lock provisioned user fields:

Select the Lock provisioned user fields check box to prevent users from editing, in My profile, any user fields that are provisioned. Those fields will appear grayed out and marked disabled, so that the user cannot change the value obtained from the identity provider. 

→ For some important limitations and issues that can arise with locked fields, please refer to the article General guidance for SSO configuration > Lock provisioned user fields.

Update the provisioned fields:

Select the If user already exists, update the user information check box to automatically update, within the platform, the values of any provisioned fields that have been changed on the identity provider end.  If you do not select this option, you will need to manually copy over any changes to keep the provisioned fields aligned.  

Click Save changes to complete the configuration.

Supported additional field types for provisioning

The Additional Field types that are supported for user provisioning in this integration are:

• Dropdown (use the dropdown ID in the Attribute statement)
• Text Field
• Fiscal Code - Country (use the ID of the country in the Attribute statement)
• Date Field (format: YYYY-MM-DD)
• Yes/No Field

Additional Field types that are not supported:

• IFrame
• File Field
• Free Text Field

Notes about user provisioning:

• If you wish to populate the country user additional field via SSO, an acceptable value would be either the Country ID or Country Name as listed in the article titled List of ISO 3166-1 Countries.
• The Language user attribute is not supported when provisioning users.

Authentication flow

As of October 26, 2021, Docebo has implemented a short-lived token in order to provide better security:

Previous authentication flow

Before October 26, 2021, the Docebo platform would send a request to the Identity Provider (IdP) and receive a persistent access token.

Each SSO has a slightly different process, but all of them return a link to Docebo with the access token in the URL:

https://mylms.docebosaas.com/learn/home;type=oauth2_response;reenter_cc=0;access_token=9b8de7ed2af145dee78aa4282bf1d3b17baf02cd;expires_in=3600;token_type=Bearer;scope=api

Short-lived token authentication flow

The updated authentication flow provides added security by replacing the IdP provided single-use short-lived token with an internally used access token:

Each SSO has a slightly different process, but all of them return a link to Docebo with the short lived token in the URL. The short lived token is a one use short lived (with a lifespan of 30 seconds) token that can be exchanged for real credentials:

https://mylms.docebosaas.com/learn/signin;type=token_exchange;exchange_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSU

Docebo automatically and internally using POST calls exchanges it for the real access token. This increases security but does not change the overall behavior of the SSO.