Introduction
This article describes how to configure the integration between Docebo and SAML using the smart configuration process. This configuration option is the default one for those that have either activated their Docebo platform or activated the SAML app in their existing platform on or after February 25, 2020. Further information on the available options for integrating SAML with Docebo.
By activating the SAML app in Docebo, you allow users to log into their learning platforms using the credentials from active sessions of other web platforms. This article will give you a step-by-step process of how to activate and configure the app using the Smart Configuration procedure.
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.
- Configuring SAML using Google, Microsoft Entra ID (Azure AD) or OneLogin
- If you are configuring SAML to work in conjunction with Google, Microsoft Entra ID (Azure AD) or OneLogin, have a look at the step-by-step configuration examples: Also, when configuring SAML, remember to set the Assertion Encryption to Unencrypted.
Activating the SAML app
Activate the SAML 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.
Configuring the SAML app with the Smart Configuration process
To begin the configuration for this app, access the Admin Menu by scrolling your mouse over the gear icon. Then, find the SAML section in the Admin Menu, and press the Settings subitem. You will then be redirected to the SAML settings page. Begin by selecting the Smart Configuration Type and flag the checkbox in the Active section. By default, this setting is not flagged when you first activate the app on your platform. You will need to enable this switch to begin configuring the app on your platform.
Then, insert the SSO URL into the text field in the SSO URL section, as well as the Issuer in the text field in the Issuer section. Please note that both of these are mandatory fields. You should ask your IT manager to provide you with this information, as necessary, and both are used to authenticate the app with your Identity Provider.
X509 certificate
You then need to upload your X509 certificate by pressing the Upload Certificate button in the X509 Certificate section. Again, this is a mandatory step in your configuration. When you upload this certificate, your platform validates the public key that you are uploading. Once the upload is complete, a message will appear in the X509 Certificate section to inform you if the uploaded certificate is valid or not. You can press the View Details button to view how Docebo read and validated your certificate, including the validity status and expiration dates. Please note that if Docebo is unable to validate your certificate, you are not able to proceed with the configuration.
Please Note: Your platform will automatically use the expiration dates in your uploaded X509 Certificate 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. If the Extended Enterprise App is active in your platform, notifications will be sent both to the main domain and all sub-domains.
Service provider signing
Then, you need to upload your Private Key File (PEM) and Certificate File (CRT) into the Service Provider Signing section using the corresponding Upload File button. This is not a mandatory step in the configuration, but you must upload these certificates if you want to use the single logout (SLO) feature.
Please Note: You cannot upload only one of these files. You must upload both the PEM and the CRT file. Please note that neither file can have any additional information (one can only have the private key, and the other can only have the cert) or you will receive an error when trying to configure the app.
- 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-----
Just as with the X509 Certificate, your PEM and CRT certificates will be validated upon upload. Once the upload is complete, a message will appear in the X509 Certificate section under each Upload File button to inform you if the uploaded file is valid or not. You can press the View Details button to view how Docebo read and validated your certificate, including the validity status and expiration dates. Please note that if Docebo is unable to validate your certificate, you are not able to proceed with the configuration.
Please Note: Your platform will automatically use the expiration dates in your uploaded PEM and CERT files to send all platform Superadmins mandatory notifications about necessary updates to your SAML configuration, such as 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. If the Extended Enterprise App is active in your platform, notifications will be sent both to the main domain and all sub-domains.
Username attribute
In the Username Attribute section, select one of the options that are auto-provided by the Identity Provider. The attribute that you select will be the username for your users in Docebo. When making your selection, make sure that the selected attribute is populated for all your users in the Identity Provider. Please note that the selected attribute must be a unique identifier. For example, if you select Family Name as username attribute, you must be sure that none of your users have the same family name. We suggest selecting Email as Username Attribute.
Also remember that if you selected the First Name and Last Name are required in order to register option in the Self Registration tab of the Advanced Settings section of Docebo Admin Menu, the Identity Provider must provide the users’ first and last names for a proper registration to the platform.
Now, you have configured all of the mandatory fields (Issuer, SSO URL and X509). If you do not want to configure the unique field, SSO behavior, logout behavior, or user provisioning, you can simply press Save Changes. Once you press the Save Changes button at the bottom of the page, you should then copy the Login URL and the Logout URLthat you see in the SAML 2.0 SP Metadatasection to pass to your Identity Provider.
If desired, you can press the Download button in the SAML 2.0 SP Metadata section to download the metadata file, but the only mandatory fields that you need to pass are the Login URL and Logout URL provided in the same section.
If you would like to configure the logout behavior, SSO Behavior, and/or User Provisioning, then do not press Save Changes yet. You can refer to the sections below to learn more about each function.
SSO behavior
To configure the SSO behavior, you can choose between two different options. Choose whether you want to show the standard platform login page, or if you want to automatically redirect to the Identity Provider. If you flag the first option, you can then flag whether you want to show the SSO button on your platform’s login page.
If you flag 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.
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.
Logout behavior
In the Logout Behavior section, you can flag the option for the user to automatically be logged out of the Identity Provider when he or she logs out of the platform. Please note that you cannot enable this option unless you have already uploaded validated PEM and CRT files on your platform. In order for the logout request to be accepted by an Identity Provider, typically the logout request must be signed, hence why you need both files to flag this option.
When this option is selected, the Logout Endpoint text field is shown for you to 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. When the Logout Behaviour option is selected, it is mandatory to insert a logout endpoint.
User provisioning
This section allows you to instantly create a user who is present in your Identity Provider but is not yet present in the learning platform database. Begin by flagging the Enable option. You can also flag the option to lock provisioned user fields, meaning that users cannot edit details in their user profiles that have been created via SAML.
Please Note: The locking provisioned user fields option will not be applied to users created with a different method on the platform even if their user additional fields will be updated via JIT provisioning afterward.
When editing the user profile, the options will be greyed out.
If you have users that already exist in both databases, you should flag the option to update the user information for the existing users. Please note that not flagging these options results in needing to manually register (enable option) or update your users (update information) in the platform.
Now, you need to specify which additional fields you want to associate between your Identity Provider and Docebo, then match the names of the fields in Docebo with the name of the fields in the Identity Provider (attribute statement).
Please Note: 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.
Please note that each field must be unique, meaning that you cannot apply the same claim to multiple fields. In the text box, type in the name of the additional field in the platform, then press the Add button. The additional field will appear in a list below, with the field name and field category automatically filled in by your platform. Insert your Identity Provider attribute statement into the corresponding text box.
You can define the language for the users created in the platform via SAML using the Language field. In doing this, once a user is created, the platform of the said user will be in the language set via the SAML claim that you configured. Once you’ve added the Language field, insert the same string into the Attribute Statement textbox that you inserted into the field in the Identity Provider that you’re matching.
Please Note: In your language field in your Identity Provider, the string must use one of the codes that the platform uses to identify languages (en = English, de = German, etc.). A full list of language codes can be found in the article List of Supported Languages. 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.
When you’re finished, press Save Changes. Now you can download the XML file and import it inside of your Identity Provider in order to set up the related authorization and complete the process.
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 | 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.
Best practices
In order to make the most of this integration, you should 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.
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
AWS certification
Please note Docebo available in the AWS SSO Catalog.