How to Activate and Manage the SAML App

Discover how the SAML APP works

Last Updated

May 9th, 2019

Reading Time

7 min

User Level

Introduction

By activating the SAML app in your Docebo LMS, you can allow users to log into their Docebo platforms using credentials from active session of other web platforms. This article will give you a step-by-step process of how to activate and configure the app.

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 OKTA

For a step-by-step look at the OKTA configuration from one of Docebo’s Implementation Specialists, refer to this document.

This app is available for Docebo Enterprise plan clients and it is optional for Growth plan clients.

Activating the SAML App

To activate the app, log into your LMS as the Superadmin. Access the Admin Menu from the gear icon in the header, then press the Add New Apps button.

saml activate

Select the Third Party Integrations tab from the tab menu. Find the SAML 2.0/ADFS Integration app in the list of apps in this tab, then press the Contact Us button in the app’s row. Read the description in the pop up box, then press the Contact Us Now button.

From here, Docebo will reach out to you regarding activating the app in your platform. Docebo will activate the app in your platform on your behalf. Once it’s activated, you can begin the configuration. Please refer to the section below to learn more.

Configuring the SAML App

To begin the configuration for this app, access the Admin Menu by scrolling your mouse over the gears icon. Then, find the SAML Settings section in the Admin Menu, and press the Settings subitem. You will then be redirected to the settings page. Begin by flagging the check box in the Active section. By default, this setting is not flagged when you first activate the app in your platform. You will need to enable this switch to begin configuring the app in your LMS.

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.

saml activate

You also need to flag which encryption algorithm (SHA-1 vs SHA-256) to use to validate IDP. 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 SHA-1. For security reasons, SHA-256 is highly recommended.

Lastly, can also flag the option to enable a service provider certificate. Some 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 flag this option, press the Choose File buttons that will appear below to upload your Private Key File and your Certificate File.

Please Note: You cannot upload only one of these files. You must upload both the private key file and the cert 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. Here is an example of a cert in PEM format, and here is an example of a private key file in PEM format.

Now, you have configured all of the mandatory fields. If you do not want to configure the unique field, SSO behavior, logout behavior, or user provisioning, you can simply press Save Changes. Now you can download the XML file and import it inside of your Identity Provider in order to setup 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.

Unique Field

By configuring this field, you are able to 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 unique field.

Please note that when the selected Unique Field is Email, in case multiple user accounts in your LMS 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.

saml unique user

Please Note: You are not able to create new users via SAML if you flag 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 between two different options. Choose whether you want to show the standard LMS 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.

sso button

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

Screen Shot 2016-06-20 at 2.04.49 PM

Please note: The Show standard login page option is supported by Docebo’s Go.Learn mobile app. If you set this option and you use SAML on your mobile app, remember that it is necessary to set also the Show SSO button on login page. The Automatic redirect to identity provider setting (and as a consequence the possibility to add a specific logout landing page) is not supported by the Go.Learn mobile app.

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 LMS. In order for the logout request to be accepted by an Identity Provider, typically the logout request must be signed. This means you will need to upload your public and private key to the Service Provider Certificate section if you would like to use the Logout Behavior. 

Screen Shot 2016-06-20 at 2.06.35 PM

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 LMS 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. 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 result in needing to manually register (enable option) or update your users (update information) in the LMS.


saml user provisioning

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 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 LMS, 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 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.

Please Note: In your language field in your identity provider, the string must use the one of the codes that the LMS uses to identity languages (en = English, de = German, etc.). For a full list of these codes, refer to this list. If the code given for this field for a specific user does not match any of the language codes of the LMS, 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 setup the related authorization and complete the process.

Best Practices for this App

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 LMS additional fields and use them to auto-populate groups, you must always logout of both the LMS 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.

Additionally, you can use the following SSO links to automatically access some areas of your Docebo LMS with an SSO login:

  • LMS homepage: /lms/index.php?r=site/sso&sso_type=saml
  • Into a Specific Course: /lms/index.php?r=site/sso&sso_type=saml&id_course=18
  • Catalogs Area: /lms/index.php?r=site/sso&sso_type=saml&destination=catalog
  • Learning Plans: /lms/index.php?r=site/sso&sso_type=saml&destination=learningplan

For certain SAML Identity providers, the standard SAML endpoints provided by the XML metadata are not allowed. In this case, Docebo has simplified endpoints. For those using Docebo 6.9 or higher, 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. For more information, refer to this PDF.