Introduction

This article outlines how to configure the integration between Docebo and SAML using the standard configuration process, which is the default option for those activating the SAML app in their existing platform before February 25, 2020. Further information on the available options for configuring the SAML integration with Docebo.

By activating the SAML app in Docebo, you can allow users to log into their learning platforms using 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 Standard Configuration process.

Configuring SAML using Okta, Google, Microsoft Entra ID (Azure AD) or OneLogin

If you are configuring SAML to work in conjunction with Okta, Microsoft Entra ID (Azure AD), OneLogin or Google, have a look at the step-by-step configuration examples:

• 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.

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 Standard Configuration process

To begin the configuration for this app, access the Admin Menu by pressing on the gear icon. Then, find SAML in the Admin Menu, and click on Manage. You will then be redirected to the settings page. Begin by changing the Configuration Type to Standard and activate 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 your identity provider ID, XML metadata (without white spaces and comments), and username attribute into the corresponding text boxes on this page. Please note that these are mandatory fields. You should ask your IT manager to provide you with this information, as necessary.

You also need to select the appropriate encryption algorithm (SHA-1 vs SHA-256) required to validate your preferred IdP (Identity Provider). For new configurations, the default value will be SHA-256. If you already have a valid configuration in your platform, the default value will be either SHA-256 or the value used in previous configurations.

Please note: As SHA-1 was deprecated in 2011, for security reasons, SHA-256 is highly recommended.

Lastly, you can also choose the option to enable a service provider certificate. Most Identity Providers or Federations may require that Service Providers hold a certificate. If you enable a certificate for your Service Provider, you will be able to sign requests and responses sent to the Identity Provider. If you activate this option, press the Choose file buttons that will appear below to upload your Private Key File and your Certificate File.

Please note: You must upload both the private key file and the cert file. Neither file can have any additional information (the file containing the private key must only contain the private key and the file containing the cert must only contain the cert), or you will receive an error when trying to configure the app. Please find example files here:

Example of a cert in PEM format:

-----BEGIN CERTIFICATE-----
MIIEJDCCAwygAwIBAgIJAKZrejX6JSfmMA0GCSqGSIb3DQEBBQUAMGkxCzAJBgNV
BAYTAklUMQ4wDAYDVQQIEwVJdGFseTEOMAwGA1UEBxMFTWlsYW4xDzANBgNVBAoT
BkRvY2VibzELMAkGA1UECxMCSVQxHDAaBgNVBAMTE3Rlc3QuZG9jZWJvc2Fhcy5j
b20wHhcNMTcwMTE5MTQzNzI3WhcNMTgwMTE5MTQzNzI3WjBpMQswCQYDVQQGEwJJ
VDEOMAwGA1UECBMFSXRhbHkxDjAMBgNVBAcTBU1pbGFuMQ8wDQYDVQQKEwZEb2Nl
Ym8xCzAJBgNVBAsTAklUMRwwGgYDVQQDExN0ZXN0LmRvY2Vib3NhYXMuY29tMIIB
IjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwS2ucXntCD59zCC27PCMr3+o
HGaqIv1m9GkNf/I0CiX/hvlYUwzWy7UP91ccLSTvJYF4917WWxhN8HBqBNYCwiOo
PkdFUXC0VF6Fxc6ti33thKqi7u8uR+ZwFTjdaeW9mJQt9qC1bdlvvbo0fmTbrcUC
5/975USpejfxtMLX4znX3DkcxD5gdBE3kgwwZmlchkSYSWngxBIbs6HtCvsVx1hE
QjiPPClWO6U3+Ho5Lb981JNVvaRVWzbcE8osE7Ogt0j7R5PNkvgFtJttPAEjZZBa
4CDM2IXRJahrF5Kyk4WBukehSn2Kw7C/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 file 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
h9prqE4BAoGBAOC4rnPb7btlW7+7Dvi3e5CO1SfKBShFhmPM6mYSC6A2uSjcjfG5
Phgjc7pDbH2Ec0wdYezJUAsXFCrNAbVECSrSfoDqncar9cJUA61xT2q2CcUbvHYJ
w7rroQk4WYXhxov9K4PiSljateyDelAxrstfRcokyHu8fT8C02k6hmcBAoGBANwR
DfckqbFfcSsWvpTGT7gVv6aDuKGgfmvrUElDgY6K6Nt49pdiExXKI3jdx7JIkqZg
t8LnXC4tFgLpFXkxHnikIW4twt0nwhe19z9phq6AW8d6rcePM7TuAVpXLzhWHPK6
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-----

If you want to make changes to the configuration and deactivate the Enable Service Provider Certificate flag, please make sure you have the certificates saved elsewhere prior to saving the configuration, as they will be automatically deleted after saving.

Now, you have configured all of the mandatory fields. If you do not want to configure the unique field, SSO (single sign-on) behavior, logout behavior, or user provisioning, you can simply press Save changes. You will then be able to download the XML file and import it into your Identity Provider in order to set up the related authorization and complete the process.

If you would like to configure the unique field, SSO behavior, logout 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.

Username attribute

In the Username attribute section, select one of the options that are provided by the Identity Provider. Here you have the following options:

Input a value from the assertions received to use as a “unique identifier”

This is a text input, you can add the attribute name but please note that the selected attribute must be a unique identifier. For example, if you select Last Name for the Username Attribute, you must be certain that none of your users have the same last name. We suggest selecting Email for the Username attribute.

Select which Docebo field this unique identifier is checked against

You can choose username, email or UUID. The selected attribute is then checked against the corresponding field in the Docebo platform. The UUID field is invisible and is a non-numeric unique user identifier.

At this stage 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 the Save changes button. Once you press the Save Changes button at the bottom of the page, you should then copy the Login URL and the Logout URL that you see in the SAML 2.0 SP Metadata section 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. Please note that the only mandatory fields that you need to pass are the Login URL and Logout URL which are also provided separately 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 following sections to learn more about each function.

Unique field

By configuring this field, you can select a shared identifier, adding more SSO flexibility, when configuring SAML and Docebo.

By default, the selected attribute is Username, but you can flag the UUID (Unique User ID) or Email attribute, depending on your preferences. We suggest using the Username as a unique field.

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

To configure the SSO behavior, you can choose whether you want to show the standard platform login page or if you want to automatically redirect to the Identity Provider.

If you select the first option, you can then choose whether you want to show the SSO button on your platform's login page.

If you select the option for an automatic redirect to Identity Provider, you can set a specific logout landing page to be used 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.

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.

Logout behavior

In the Logout behavior section, you can select the option for the user to automatically be 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. To use this feature, you will likely need to upload your public and private keys to the Service Provider certificate section.

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 platform database. Begin by activating the Enable option.

You can also enable the option to lock provisioned user fields, meaning that users are unable to 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 unavailable options will be greyed out.

If you have users that already exist in both databases, you should enable the option to update the user information for the existing users. Please note that not enabling these options result in needing to manually register (enable option) or update your users (update information) in the platform.

Next, you need to specify which additional fields should be associated 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 (link opens in a new tab).

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 your identity provider that you’re matching.

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.

Important notes about user provisioning:

• Each field must be unique, meaning that you cannot apply the same name 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.
• In the language field in your identity provider, the entry must use one of the language codes (24kb, PDF) 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.
• 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 provision the users’ first and last names to facilitate a proper registration in the platform. Please note that that country fields, if used, need to be sent in the correct format by your Identity Provider and if you have previously set email as mandatory then it also needs to be added as a field.

Best practices

In order to make the most of this integration, you should set up groups that are auto-populated, 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 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 platform and the identity provider. Please make sure you've enabled the option in the Logout behavior section. Without enabling 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. If this applies to your identity provider, Docebo has simplified endpoints available for your platform. Docebo has SAML 2.0 metadata without the query string part available, making it acceptable to 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

If the custom domain needs to be configured after SSO has already been configured, please follow these steps:

• Setup up the custom domain in your Docebo platform, please see Domain management: Configuring custom domains for more details.
• Log in to the custom domain site you created in your Docebo platform
• Access the Admin Menu from the gear icon in the top right corner of the page
• Select the Manage option in the SAML section
• On the SAML settings page, download SAML 2.0 Metadata by pressing the Download button in the SAML 2.0 SP Metadata section
• Once the download is complete, log into your Identity Provider account
• Access Existing Relying Party Trust
• Import the metadata that you downloaded from the SAML settings page

Tips and tricks

• Depending on the user fields you wish to import, you can choose whether to import users via CSV, SAML, or Automation app. This table provides a comparison of the fields you can import via Automation or via SAML SSO:
  

  LMS User Data Field	Automation	SAML SSO
  User Name	X	X
  First Name	X	X
  Last Name	X	X
  Email	X	X
  Level	X
  Profile Name	X
  Branch Name	X	X
  Branch Code	X	X
  Branch Name Path	X
  Branch Code Path	X
  Password	X
  Hashed Password	X
  Active	X
  Force Password Change	X
  Expire On	X
  Language	X	X
  Date Format	X
  Time Zone	X
  New User Name	X
  User ID
  Is Manager	X
  UUID
  Direct Manager	X (Note: to populate this, the associated user must have the “Is Manager” flag set to 1)
  Other Manager Types
  Additional Fields	X	X

• 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.

AWS certification

Please note Docebo is available in the AWS SSO Catalog.