Docebo for SAML - Microsoft ADFS 2.0

Introduction

By integrating your Docebo with Microsoft ADFS 2.0 (and thus, Docebo's SAML App), your Docebo users will be able to log in to their platforms without entering Docebo user credentials, provided that they are already logged into your AD domain.

Please note: Docebo does not provide support for ADFS or other third party technologies implementing the SAML 2.0 protocol. This document is to be intended only as a set of best practices for IT administrators. Docebo cannot be held liable for any damage or malfunctioning due to an incorrect ADFS configuration.

This SAML integration will also work with Azure AD, though the Azure setup may differ slightly from the steps and screenshots provided here for ADFS Enterprise. Learn more about setting up OpenID Connect with Azure AD.

Best practice: When an SSO integration and a custom domain are set up at the same time, it is strongly suggested to configure the custom domain first. The endpoint URLs needed for the SSO integration are dependent on the URL of the platform. For more information about custom domains, please see Domain Management: Configuring custom domains.

Step 1: Retrieve SAML 2.0 configuration from ADFS

Now, you need to open the ADFS 2.0 Management via Start → Administrative Tools → ADFS 2.0 Management. Then, right-click on Service in the left panel, and choose Edit Federation Service Properties from the menu.

The General Tab contains the Federation Service Identifier, which is the Identity Provider URL. Copy this URL into your clipboard, as you’ll have to enter it into your platform later. Our Identity Provider example for this tutorial will be http://adfs.adatum.com/adfs/services/trust.

Step 2: Activating the SAML Docebo 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. Please refer to the Configuring the SAML Docebo App section to learn more.

Step 3: Configuring the SAML Docebo app

To begin the configuration for this app, access the Navigation menu > Add-ons and integrations (jigsaw icon) > SAML. You will then be redirected to the settings page. Select the Active checkbox in order to enable the configuration. This option is not enabled when activating the app in your platform. Therefore, enable it to proceed with the app configuration in your platform.

Begin by inserting your identity provider ID, XML metadata, and username attribute into the corresponding text boxes on this page:

Identity Provider ID

This is the Federation Service Identifier from Step 1.

XML Metadata

Open your web browser and go to the following URL:

https://domain.name/FederationMetadata/2007-06/FederationMetadata.xml 

Replace domain.name with your ADFS 2.0 domain name, such as adatum.com. Then, open the downloaded XML file with a text editor, such as Notepad, and copy its entire content. Then, paste it into the XML Metadata field in your platform.

Username Attribute

This is the attribute statement identifier configured in Step 4. (e.g. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress).

Please note that the Download button only appears after you have inserted all of the mandatory information on this page and pressed Save Changes. Once it appears, press the Download button at the bottom of the page, then save the XML file to your computer.

Now, you can flag which encryption algorithm (SHA-1 vs SHA-256) to use to validate the 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 SHA-1. SHA-256 is recommended for security reasons.

Then, you can 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 that you cannot upload only one of these files. You must upload both files.

SSO Behavior

To configure the SSO behavior, you can flag 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.

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.

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 flagging the Enable option. 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 names of the fields in the Identity Provider (attribute statement). 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. When you're finished, press Save Changes.

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

Step 4: ADFS 2.0 Relying Party Trust configuration

The quickest way to configure the Relying Party Trust in ADFS is to download the Service Provider metadata XML file from Docebo, then import it inside ADFS. Begin by logging into your platform (remember to use HTTPS) as a Superadmin. Then access the Navigation menu > Add-ons and integrations (jigsaw icon) > SAML. Now, return to your ADFS Management Console, then select Relying Party Trusts in the left panel under Trust Relationships. Right-click on Relying Party Trusts and choose Add Relying Party Trust from the menu that will appear.

Then, select the option to Import data about the relying party from a file. Next, press Browse, then locate the Metadata XML file that you downloaded from Docebo. Press Next, ignore the popup message, enter a distinctive display name, and click Next again. Now, select Permit all users to access the relying party, and press Next to finish.

In the column in the center, right-click on the relying party you’ve just created, then select Properties. In the Advanced Tab, choose either SHA-1 or SHA-256 depending on the setting chosen in Step 3: Configuring the SAML Docebo App as the Secure Hash Algorithm, and then press OK.

Please note: You must make sure that the secure hash algorithm settings in Docebo and Microsoft are the same, if you select SHA-1 in one system and SHA-256 in the other, you will not be able to connect.

Step 5: ADFS 2.0 Claim Rules configuration

In order to configure proper communication between your ADFS and Docebo, you should define the Claim Rules by right-clicking on the relying party you’ve just created (e.g. Docebo ADFS) and then selecting Edit Claim Rules.

On the Issuance Transform Rules tab, press Add Rules. Then, select Send LDAP Attributes as Claims and press Next. Now, define the Claim Rule name and select Active Directory in the Attribute Store dropdown menu. Under Mapping of LDAP attributes to outgoing claim types, select all of the attributes that you want to export as claims for the SSO. Examples are:

• LDAP Attribute: E-Mail-Addresses; Outgoing Claim Type: E-Mail Address
• LDAP Attribute: Given-Name; Outgoing Claim Type: Given Name
• LDAP Attribute: User-Principal-Name; Outgoing Claim Type: UPN

Add a second rule by following the same procedure. Select Transform an Incoming Claim, then press Next. Now, define the Claim Rule name, and set the Incoming claim type as one of the previously configured attributes. Then, set the Outgoing claim type as Name ID. Finally, set the Outgoing name ID format as Transient Identifier. Then, press Finish. The incoming claim type should match the username of your users inside Docebo for the SSO to work properly.

Step 6: SSO in action

Even after you’ve successfully configured SAML for ADFS, you'll notice that your users will still see the standard Docebo login form (with username and password). To change this, you need to give your platform access to a subset of users currently not in your AD user registry. Alternatively, if you want to let your users use SSO inside Docebo, you should use this URL:

https://yourlms/index.php?r=site/sso&sso_type=saml

Replace yourlms with your custom platform domain.

User provisioning from Active Directory to Docebo

Once SAML and ADFS are properly configured, any user logged into your Windows Active Directory domain can access the platform without entering any credentials. However, this requires that the following requirements are met:

• The user trying to use SSO should have a valid Docebo account created before SSO is attempted. You can learn more about creating users with SAML, or you can learn more about creating users in your platform.
• There must be a match between the platform username and the Username claim attributed (see Step 4).