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:
- Okta configuration
- Microsoft Entra ID (Azure AD) Configuration
- OneLogin Configuration Example
- Google configuration (opens in a new tab)
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 Admin menu > SAML > Manage.
For an extended enterprise client:
- Select Admin menu > Extended Enterprise > Manage.
- 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. →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. |
SSO behavior (optional) |
In this section you can configure how users will log in to the platform using SSO. For more information see the chapter 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 encryption algorithm (SHA-1 or SHA-256) required to validate your identity provider. |
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. |
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. → 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: |
SSO behavior (optional) |
In this section you can configure how users will log in to the platform using SSO. For more information see the chapter 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. |
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.
|
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 PEM format:
-----BEGIN CERTIFICATE-----
MIIEJDCCAwygAwIBAgIJAKZrejX6JSfmMA0GCSqGSIb3DQEBBQUAMGkxCzAJBgNV
BAYTAklUMQ4wDAYDVQQIEwVJdGFseTEOMAwGA1UEBxMFTWlsYW4xDzANBgNVBAoT
BkRvY2VibzELMAkGA1UECxMCSVQxHDAaBgNVBAMTE3Rlc3QuZG9jZWJvc2Fhcy5j
b20wHhcNMTcwMTE5MTQzNzI3WhcNMTgwMTE5MTQzNzI3WjBpMQswCQYDVQQGEwJJ
VDEOMAwGA1UECBMFSXRhbHkxDjAMBgNVBAcTBU1pbGFuMQ8wDQYDVQQKEwZEb2Nl
Ym8xCzAJBgNVBAsTAklUMRwwGgYDVQQDExN0ZXN0LmRvY2Vib3NhYXMuY29tMIIB
IjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwS2ucXntCD59zCC27PCMr3+o
HGaqIv1m9GkNf/I0CiX/hvlYUwzWy7UP91ccLSTvJYF4917WWxhN8HBqBNYCwiOo
PkdFUXC0VF6Fxc6ti33thKqi7u8uR+ZwFTjdaeW9mJQt9qC1bdlvvbo0fmTbrcUC
5/975USpejfxtMLX4znX3DkcxD5gdBE3kgwwZmlchkSYSWngxBIbs6HtCvsVx1hE
QjiPPClWO6U3+Ho5Lb981JNVvaRVWzbcE8osE7Ogt0j7R5PNkvgFtJttPAEjZZBa
4CDM2IXRJahrF5Kyk4BWukehSn2Kw7C/lf5SD2n0tFiiqHdK8mLvQEC0h+gJ2wID
AQABo4HOMIHLMB0GA1UdDgQWBBTcGhjhW6mD31Cox6ftIxjERuYj6TCBmwYDVR0j
BIGTMIGQgBTcGhjhW6mD31Cox6ftIxjERuYj6aFtpGswaTELMAkGA1UEBhMCSVQx
DjAMBgNVBAgTBUl0YWx5MQ4wDAYDVQQHEwVNaWxhbjEPMA0GA1UEChMGRG9jZWJv
MQswCQYDVQQLEwJJVDEcMBoGA1UEAxMTdGVzdC5kb2NlYm9zYWFzLmNvbYIJAKZr
ejX6JSfmMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEFBQADggEBAEU2JOtj60v3
1wIX7iIUwMM2UsbE52ZOAM+xRSUIJoDJvuvcNNT45fNCAz5V5HTjyhZvd81bJ/8r
8AT47YYHO2ngWxKWklbRdvWuDhwvEFulUnVt5DcVVGy3JgH98hIBNTf+BMDGkm1z
HviID1Zuaa5KByCKTbr2ib2nVLDqdJMvPyT8yaWd5VQxb4F5WqUz8EjS12KtLnHc
4Uh51/fJA8StUyADaeb74Uj/e/0/XIvsOIGUuBzhF3dfPBGWXCwTAbQmSaqk/B3n
wAUznTV6BahfIeZJz5PmI7VEkw+3AdGwwhxrGPxcKHXf/5yDyPdjOOuYsDXAV54n
PnHnWAxctA0=
-----END CERTIFICATE-----
Example of a private key in PEM format:
-----BEGIN RSA PRIVATE KEY----- MIIEowIBAAKCAQEAwS2ucXntCD59zCC27PCMr3+oHGaqIv1m9GkNf/I0CiX/hvlY UwzWy7UP91ccLSTvJYF4917WWxhN8HBqBNYCwiOoPkdFUXC0VF6Fxc6ti33thKqi 7u8uR+ZwFTjdaeW9mJQt9qC1bdlvvbo0fmTbrcUC5/975USpejfxtMLX4znX3Dkc xD5gdBE3kgwwZmlchkSYSWngxBIbs6HtCvsVx1hEQjiPPClWO6U3+Ho5Lb981JNV vaRVWzbcE8osE7Ogt0j7R5PNkvgFtJttPAEjZZBa4CDM2IXRJahrF5Kyk4BWukeh Sn2Kw7C/lf5SD2n0tFiiqHdK8mLvQEC0h+gJ2wIDAQABAoIBAQCqpZT0zxURdEqi GMAe3Hwax/UUaaif0iOxgl+Xh7hqwphQflGEw9G3D5I0F3JfesH66r2WH+PRgs3O uS8eaIL1RpRnt4PHZn0WDo2zaFir4akAyc+2q/jBMRIP3TTSSE1MzJExzVOX3z0z Z5rZkHTysxdXI7wpkpb3zRWqbXhSUwyvLxHFWOamRNJb/LjiLko30pblyGZG744Q XmoHrDcpN46OpZTITMqF8SJbnJXKKPzIWRvTVxVRUzVwth4OgXFNPkfyJgsZ1DD+ wFvH+kI72l9yhF9UcI0IoEbk6I5Ao3O6O3+X6FV2YJhFPb4vfhKJI1irMS+rpCzB h9prqE4BAoGBAOC4rnPb7bltW7+7Dvi3e5CO1SfKBShFhmPM6mYSC6A2uSjcjfG5 Phgjc7pDbH2Ec0wdYezJUAsXFCrNAbVECSrSfoDqncar9cJUA61xT2q2CcUbvHYJ w7rroQk4WYXhxov9K4PiSljateyDelAxrstfRcokyHu8fT8C02k6hmcBAoGBANwR DfckqbFfcSsWvpTGT7gVv6aDuKGgfmvrUElDgY6K6Nt49pdiExXKI3jdx7JIkqZg t8LnXC4tFgLpFXkxHnikIW4twt0qrhe19z9phq6AW8d6rcePM7TuAVpXLzhWHPK6 UY4PESl4SBzoB4yyWKCDBcsDBJrOh8cYCWFg+ezbAoGADa9ReF7BSFR/jNqAW+cY kEISevzTeZNaTsOQ1qxsptIOTo232yuTu3aVOpeWiMJDHzR+3SOZS0OZh826N+av xDrTV1hySUH5kl75ZluLIY16ZNV+kZWgpMZqpRwYX43TQH0nZD2ol2aiQ4fyL+YG pf3kSx4YU2i0G905MKROwQECgYAMMUmzyq04LZCIkZ8HgSFDkrjmkd+13L2EXyo4 lOvlqN6T4lTPOFjUWTmz5Z29y/WMEEm+G7FowYi5qo5NA6KrjnRntVNZi21egO9s 7PzQSD5NhAeCyfVUbedXSQNNvL+n1xjTpRQPVyGvsE9SxULRydCVWdp0dULijftf EM9oBwKBgBzpA1Qj9fgj7hOVCDdrqcuX3/qWmuwiqV+bjGK2FPrW/7G5BSNsj8Gc /KuXgcZCPMRlobEue5ha0kFnPbUGhYngqJQEmsodkbK3Kz21zHOP4nTc3FublfLo Hzsrl5PEUsehiA+lf6TZtW/Jlo5vnrGEchSgTau09I4meN803DdX -----END RSA PRIVATE KEY-----
SSO behavior
In this section, you can configure how users will log in to the platform through SAML single sign-on. There are two options available: Show standard login page and Automatic redirect to identity provider.
Show standard login page:
With this option, when users click Sign in on the platform header, they will see the normal Sign in window with fields for entering the platform credentials.
- If you also select Show SSO button on login page, underneath the username and password fields, users will see a button to Sign in with SAML SSO.
- When they click this SSO button they are redirected to a page for authenticating with the SAML identity provider, and if the authentication is successful they are signed in to the platform.
Please note: If you do not choose to show the SSO button, users will be unable to initiate SSO login from the platform home page.
Automatic redirect to identity provider:
With this second option, users do not see the platform’s sign-in window and do not need to click any SSO login button. Instead, when they attempt to access the platform URL, they are automatically redirected to the page for authenticating with the SAML provider. Then, if the authentication is successful, they are signed in to the platform.
Please note that with the automatic redirect option users cannot view the public page and they are unable to choose between alternative sign-in options. With this method, they are required to authenticate with the configured identity provider.
With automatic redirect, when a user logs out of the platform they will be sent to a default “logout successful” landing page. There they can either close the page or or use the re-login button to authenticate again.
If desired, you can redirect users who log out to a different page, by entering its URL in the Logout landing page field.
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. |
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.
→ Note, however, that a Superadmin or Power User can still edit the values of these locked provisioned fields in User management with the following limitation: Only the user information fields can be edited, whereas additional user fields, if locked, cannot be edited by anyone.
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.
Tip: locked fields with multiple SSO providers
On platforms that have more than one SSO provider active for the same domain, if any SSO provider (even if not fully configured) has provisioning Enabled with Lock provisioned fields set to ON, then those provisioned fields, listed in the Add fields area, will always be locked for the users of that domain, even when logging in with a different SSO.
→ This will happen even if the SSO actually used for login does NOT have a lock on those provisioned fields, and/or does not list those fields in the Add fields box.
→ This interaction occurs only when there are multiple SSO providers on the same root platform, or on the same extended enterprise client/domain. However, the locked fields of one domain will not have any effect on other domains.
Click Save changes to complete the configuration.
Please note that all the provisioning settings described here apply only to users who log in via SSO (single-sign-on). For example, locked provisioned fields will not be disabled for users who log in using platform credentials.
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 |
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.