SAML legacy configuration – Docebo Help & Support

Disclaimer: This article outlines how to use the Legacy SAML configuration. If your platform has been migrated to the new SAML configuration, refer instead to the article Docebo for SAML - Smart and Standard configuration.

Introduction

The SAML app on your platform enables you to configure single sign-on (SSO) using a variety of identity providers. In this way, users can log into their learning platform using the credentials from active sessions of other web platforms.

Please note that the platform provides two options for SAML configuration: Smart and Standard. For an overview of the differences refer to the article Introduction to Docebo for SAML.

This article provides general instructions for both the Smart and Standard configurations.

Configuring SAML with specific identity providers

If you are configuring SAML to work in conjunction with Okta, Microsoft Entra ID (Azure AD), OneLogin or Google, refer also to the following articles which provide specific instructions:

Also, when configuring SAML, remember to set the Assertion Encryption to Unencrypted, as this setting is fully supported.

Prerequisites

The SAML app needs to be activated on your platform, as described in the article Managing apps and features.

If you are planning to set up SAML single sign-on for a custom domain or for a secondary domain, you must configure the domain first in Domain management.

Access the SAML settings page in the platform

To begin, open up the SAML settings page and select the desired configuration type.
→ You must do this on the same platform (main platform or extended enterprise client) for which you are configuring single sign-on.

For a main platform:

Select Navigation menu > Add-ons and integrations (jigsaw icon) > SAML.

For an extended enterprise client:

Select Navigation menu > Configuration (spanner icon) > Platform setup and tools > Extended Enterprise management.
Click the gear icon next to the client for which you are configuring SSO.
In the vertical navigation select SAML 2.0 settings. Then select Enable custom settings for this client.

Tip: Note that the SAML 2.0 settings page for will look the same in both cases (main platform or extended enterprise client).

Once the SAML 2.0 settings page is open select whether to use the Smart or Standard configuration type. The configuration with the Smart option is slightly simpler, but if required you can also switch to the Standard configuration type.

Warning: If there is an existing SAML configuration on the page, changing from Smart to Standard or vice versa will lose your previous settings, even if you do not click Save changes.

Then select the Active check box to enable the configuration fields. Some of the fields that you see are specific to the type of configuration you selected (Smart or Standard) while other settings are common to both.

Move on to configure the SAML settings for your chosen configuration type as described in the following chapters: SAML settings for Smart configuration or SAML settings for Standard configuration.

When you have finished click Save changes.

SAML settings for Smart configuration

This chapter covers the settings to configure if you select the Smart configuration type.

SAML settings field (Smart configuration)	Notes
SSO URL	The HTTP SAML endpoint of your identity provider. This is the actual web address where the SAML requests are sent to initiate authentication
Issuer	Obtained from the identity provider. This is a unique identifier for the SAML service of your account with the identity provider. For example, for OneLogin it is the Issuer URL, for Microsoft Entra it is the Microsoft Entra Identifier.
X509 certificate	Here you need to upload the X.509 certificate that you obtain from the identity provider. → Your X.509 certificate will be validated upon upload. See the chapter Certificate validation and expiration.
Enable service provider certificate (optional)	This certificate enables the platform to sign SAML authentication requests and assertions sent to the identity provider. Some identity providers / federations may require that service providers hold a certificate. Here you can upload a CRT certificate file and a PEM private key file. For more information, see the chapter Service provider certificate. (Uploading this certificate is optional, but required if you want to configure Logout behavior) →Your PEM and CRT certificates will be validated upon upload. Including checking that they are a matching key pair. See the chapter Certificate validation and expiration.
Username attribute	Set which identity provider field (attribute) will be used to uniquely identify the user within the learning platform. - The selected field must be populated for all your users on the identity provider side, and also distinct for every user. - The identity provider field you select in Username attribute will be matched to the Username field in the platform.
SSO behavior	In this section, you can configure how users log in to the platform with SSO. You can either: - Display the standard login window, and from there users click a button to continue to the SSO provider - Automatically redirect them to the provider without showing the login window For more information see the article General guidance for SSO configuration > SSO behavior.
Logout behavior (optional)	Select this option if you want users to be automatically logged out of the identity provider when they log out of the platform. → To be able to configure this, you must first have uploaded the Service provider certificate (CRT and PEM files) When this option is selected, the Logout endpoint text field appears. Here you must define the URL where users will land upon logging out from the platform and from the identity provider. Thanks to this configuration, users can land on a different URL from the one used for SSO.
SAML 2.0 SP metadata	You can copy the Entity ID, Login URL and Logout URL displayed here to enter them into the configuration of your identity provider. Here you can also download the metadata file, if required by your provider.
User provisioning (optional)	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. For instructions see the chapter User provisioning.

Certificate validation and expiration

Only for the Smart configuration, the platform automatically validates the uploaded certificates, and also tracks and notifies you of their expiration. This applies to both the X.509 certificate and the Service provider certificate files.

Validation: Once the certificate file upload is complete, a message will appear to inform you if the uploaded file or files are valid or not.

You can press the View details button to check how the platform read and validated your certificate files, including the validity status and expiration dates.

Expiration:

Your platform will automatically use the expiration dates in your uploaded certificates to send all platform Superadmins mandatory notifications about necessary updates to your SAML configuration when your expiration date is approaching (30, 15, 5 and one days before the certificate expiration). Notifications cannot be modified or disabled. In this way, you are able to update your SAML configuration before it expires, so your users aren’t blocked from logging into the platform. For extended enterprise platforms, notifications will be sent for SAML configurations on both the main platform and on all extended enterprise clients

SAML settings for Standard configuration

This chapter covers the settings to configure if you select the Standard configuration type.

SAML settings field (Standard configuration)	Notes
Identity provider ID	Obtained from the identity provider. This is a unique identifier for the SAML service of your account with the identity provider. For example, for OneLogin it is the Issuer URL, for Microsoft Entra it is the Microsoft Entra Identifier.
Enable service provider certificate (optional)	This certificate enables the platform to sign SAML authentication requests and assertions sent to the identity provider. Select this check box to upload a CRT certificate file and a PEM private key file. For more information, see the chapter Service provider certificate. Note that for the standard configuration, the uploaded files are not automatically validated. It is up to you to verify that they are a matching key pair. ! If you change a pre-existing configuration and deactivate the Enable service provider certificate flag, ensure you have the certificates stored elsewhere, as they will be automatically deleted when you save the SAML configuration.
Signature algorithm	Select the SHA-256 encryption algorithm to validate your identity provider. You must also set the same one on the identity provider side. Note: The SHA-1 algorithm is no longer supported.
XML metadata	In this field you need to paste in the contents of the XML metadata file obtained from your identity provider.
Username attribute	Set which identity provider field (attribute) will be used to uniquely identify the user within the learning platform. - The selected field must be populated for all your users on the identity provider side, and also distinct for every user. - The identity provider field you select in Username attribute will be matched to the platform field selected in Unique field.
Unique field (default is Username)	Set which user field within the platform (Username, UUID, Email) will be mapped to the identity provider field set in Username attribute. - 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. - Otherwise, the SSO user does not yet exist in the platform (but can be automatically created if you configure User provisioning). → Here it is recommended to set the Username field. Note: The UUID is a read-only unique user identifier within the platform Important notes about Unique fields: When the selected Unique Field is Email, in case multiple user accounts in your platform have the same email address, when one of the user accounts is logging into the platform via SAML, the most recently created user account will be the account that is logged into the platform. You are not able to create new users via SAML if you select the UUID attribute, as the UUID does not exist until a user is created in the platform.
SSO behavior	In this section, you can configure how users log in to the platform with SSO. You can either: - Display the standard login window, and from there users click a button to continue to the SSO provider - Automatically redirect them to the provider without showing the login window For more information see the article General guidance for SSO configuration > SSO behavior.
Logout behavior (optional)	Here you can set whether the user should also be automatically logged out of the identity provider when they log out of the platform. For the logout request to be accepted by an Identity Provider, typically the logout request must be signed. → For this feature to work correctly, you will likely need to upload your Service provider certificate (CRT and PEM files).
SAML 2.0 SP metadata	Once you have done all the other configurations, you can press Save changes at the bottom of the page. Then click Download to download the XML metadata file. Open it in a text editor to copy the values required by your identity provider, such as Login URL or Logout URL, and paste them into the configuration on the identity provider end. In some cases you may have to upload the entire metadata file to the identity provider.
User provisioning (optional)	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. For instructions see the chapter User provisioning.

Service provider certificate

The Service provider certificate is primarily used for signing and encryption in SAML-based authentication. It consists of:

Certificate (CRT file): Contains the public key and identifying information about the service, signed by a trusted Certificate Authority (CA).
Private Key (PEM file): This is the corresponding private key that can be used to create digital signatures.

For example, when sending a SAML authentication request to the identity provider (IdP), the platform signs the request using its private key (in the PEM file). The IdP then verifies the signature using the public key in the certificate (CRT file).

You must upload both the private key file and the certificate file. Neither file can have any additional information (the PEM file must contain only the private key and the CRT file must contain only the certificate).

In addition, The CRT and PEM file hashes must match, meaning that the public key in the certificate corresponds to the private key. This ensures that they were generated together as a key pair. In the Smart configuration, this is automatically validated. Whereas in the Standard configuration you are responsible for ensuring the correctness of the uploaded files.

Example of a certificate in CRT format:

Example of a private key in PEM format:

Important notes about SSO behavior: The SSO behavior is tested against standard Identity Providers. Generally, since Docebo starts the Identity Provider initiated SSO, the first call is not secured since users still need to enter their own credentials into the Identity Provider. The configuration on the Identity Provider side will create a secure channel after that.

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 identity provider.

Tip: By default, a user is considered to already exist in the platform if their Username matches the identity provider field you set as the Username attribute.
Only in the Standard SAML configuration, you can if needed set a different matching field (UUID or Email instead of Username) in the Unique field.

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, by default with platform Username = the provider field set in Username attribute.
→ Note for standard configuration: If instead of Username a different unique field for matching is set, please note that the UUID option will not permit the creation of provisioned users, and that the Email option will work correctly only if all users have distinct emails.

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, type the name of a platform user field or user additional field into the text box at the top, then click Add. .The entered field will appear under the Field name heading.
Now, in the Attribute statement box alongside the newly added field, enter the matching attribute from the identity provider that you want to use for that field.

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 attribute, or vice versa.

Supported user fields for SAML provisioning:

Username, First name, Last name, Email, Branch name, Branch code, Language and Additional fields.

Field in platform	Notes
Username
First name Last name	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.
Email
Branch name
Branch code
Language	In the language field in your identity provider, the entry must use one of the language codes that the platform uses to identify languages (en = English, de = German, etc.). If the code given for this field for a specific user does not match any of the language codes of the platform, the user will be given the set default language of the platform upon activation.
Additional fields	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. 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.

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.

Comparison of user fields with SAML and Automation app

Depending on the field, you can import them via CSV, via SAML, or via Automation App.

This is a comparison of the fields you can import via Automation or via SAML SSO:

Docebo user data field	Automation app	SAML SSO
Username	Yes	Yes
First name	Yes	Yes
Last name	Yes	Yes
Email	Yes	Yes
Level	Yes
Profile name	Yes
Branch name	Yes	Yes
Branch code	Yes	Yes
Branch name path	Yes
Branch code path	Yes
Password	Yes
Hashed password	Yes
Active	Yes
Force password change	Yes
Expire on	Yes
Language	Yes	Yes
Date format	Yes
Time zone	Yes
New username	Yes
User ID
Is manager	Yes
UUID
Direct manager	Yes (Note: to populate this, the field is called Is Manager)
Other manager types
Additional fields	Yes	Yes

Please note: Branch creation in SAML is not supported via CSV import. All users will be automatically placed in the root branch in single-domain configurations or, if the Extended Enterprise App is active, in the branch corresponding to the relevant sub-domain.

When determining your provisioning strategy, consider whether you want to monitor your users or send notifications prior to go live. If you do, you will need to preload these users.

Best practices

Auto populating groups

In order to make the most of this integration, you can set up automatic groups, then use Docebo’s Enrollment Rules App to automatically enroll these groups into courses or learning plans. Thus, when a new user is created, you do not have to manually assign them to groups, courses, or learning plans.

Please note that in order to correctly pair newly added SAML fields and newly added platform additional fields and use them to auto-populate groups, you must always log out of both the learning platform and the Identity Provider. Therefore, please make sure you’ve enabled the option in the Logout Behavior section. Without flagging this option, this user provisioning process will not occur.

Simplified SAML endpoints

For certain SAML Identity Providers, the standard SAML endpoints provided by the XML metadata are not allowed. In this case, Docebo has simplified endpoints. Docebo has SAML 2.0 metadata without the query string part available, thus making it acceptable by OpenSAML:

http(s)://exampleLMS.docebosaas.com/simplesaml/modules/saml/sp/saml2-logout.php/default-sp

http(s)://exampleLMS.docebosaas.com/simplesaml/modules/saml/sp/saml2-acs.php/default-sp

Configuring a domain after SAML SSO has been configured

If a custom domain or secondary domain needs to be configured after SAML SSO has already been configured, you will need to:

First, fully set up up the custom domain or secondary domain in your platform, as instructed in the corresponding article: Domain management: Configuring custom domains or Domain management: Configuring secondary domains.
Next, access the SAML settings page and, in the SAML 2.0 metadata section, copy the new information (such as Entity ID, Login URL or Logout URL) and use it to update the configuration on the identity provider side. In this way, the identity provider will be connected to the newly configured domain rather than to the previous platform URL.

AWS certification

Docebo is available in the AWS SSO Catalog.

Other notes

Please Note: To prevent improper SAML configurations, Docebo has implemented a blocker as of April 2018. If the connection continues to bounce back and forth, Docebo has added a stopper that will show an error page. Additionally, the browser that started the loop will be timed out for one hour.