Docebo for SAML - Okta single sign-on configuration example

Introduction

By activating the SAML app in Docebo, users can log into their learning platforms using credentials from active sessions of other web platforms. This article will give you an example for configuring Okta as an Identity Provider using SAML.

In order to prepare for this integration, you should make sure you have the SAML Single Sign On application installed on your platform. For more instructions, please read Docebo for SAML - Smart and Standard configuration.

Before starting

• Make sure you have the SAML app activated. For more information please see read Docebo for SAML - Smart and Standard configuration.
• Confirm that you have a Superadmin account to access your Docebo Learn platform before proceeding.
• Confirm that you have Okta admin-level access
• If you plan on creating users in Docebo via Okta, create the User Additional Fields that will be populated from Okta before proceeding. For more information please see Creating and managing User Additional Fields.
• If you are using, or plan on using a custom domain for your Docebo platform (any domain that does not contain docebosaas.com), this domain should be configured in Docebo and reachable via a browser before proceeding. For more information on custom domains please see Domain Management.

Configuring Okta with SAML

Configuring an Okta application

Log in to your Okta portal and click on the Admin button. You will need Okta administrator privileges.

Next, in the Admin Bedienfeld, click on the Applications drop down menu item and select Applications. In the Applications window, select Create App Integration.

In the Create a new app integration window, select the SAML 2.0 radio button, press Next to continue.

In the General Settings tab of the Create SAML Integration window, enter a name for your integration and, optionally, upload an application logo image. Press the Next button to continue.

Next, open a new browser tab or window and navigate to your Docebo Learn Platform. Press on the gear icon in the top right corner and locate SAML. Press Manage to enter the SAML 2.0 configuration screen.

Once there, press the Download button in the SAML 2.0 SP Metadata section.

Open the downloaded file with a plain text editor such as Notepad++, Sublime Text, Kate or others.

Look for the first XML tag labeled md:AssertionConsumerService, the location for this tag should be a URL. Copy this URL to your clipboard (do not include the quotations). Below is an example of the metadata you would see in a text editor with the URL highlighted. Please note that the URL in your metadata will be slightly different as the URL makes reference to your specific Docebo URL or instance. If you are using a custom domain, make sure this link does not contain docebosaas.com. If it does, log out of the Docebo platform and log in to your custom domain URL before downloading the Metadata.

<?xml version="1.0"?>
  <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" 
entityID="https://academy70.docebosaas.com/lms/index.php">
  <md:SPSSODescriptor 
protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol 
urn:oasis:names:tc:SAML:2.0:protocol">
    <md:SingleLogoutService 
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-logout.php/default-sp"/>
    <md:SingleLogoutService 
Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-logout.php/default-sp"/>
    <md:AssertionConsumerService 
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-acs.php/default-sp" index="0"/>
    <md:AssertionConsumerService 
Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml1-acs.php/default-sp" index="1"/>
    <md:AssertionConsumerService 
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-acs.php/default-sp" index="2"/>
    <md:AssertionConsumerService 
Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml1-acs.php/default-sp/artifact" index="3"/>
  </md:SPSSODescriptor>
  <md:ContactPerson contactType="technical">
    <md:GivenName>Administrator</md:GivenName>
    <md:EmailAddress>tech24@docebo.com</md:EmailAddress>
  </md:ContactPerson>
</md:EntityDescriptor>

Return to the Okta browser tab. Paste the URL in your clipboard into the text box labeled Single Sign On URL. Check the box below the text file to Use this for Recipient and Destination URL.

Return to your metadata file in your text editor. On the second line of the file there should be a declaration labeled entityID. Copy the URL that entityID is equal to (do not include the quotations) to your clipboard. An example entityID is highlighted below:

<?xml version="1.0"?>
  <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" 
entityID="https://academy70.docebosaas.com/lms/index.php">
  <md:SPSSODescriptor 
protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol 
urn:oasis:names:tc:SAML:2.0:protocol">
    <md:SingleLogoutService 
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-logout.php/default-sp"/>
    <md:SingleLogoutService 
Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-logout.php/default-sp"/>
    <md:AssertionConsumerService
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-acs.php/default-sp" index="0"/>
    <md:AssertionConsumerService 
Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml1-acs.php/default-sp" index="1"/>
    <md:AssertionConsumerService 
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-acs.php/default-sp" index="2"/>
    <md:AssertionConsumerService 
Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml1-acs.php/default-sp/artifact" index="3"/>
  </md:SPSSODescriptor>
  <md:ContactPerson contactType="technical">
    <md:GivenName>Administrator</md:GivenName>
    <md:EmailAddress>tech24@docebo.com</md:EmailAddress>
  </md:ContactPerson>
</md:EntityDescriptor>

Return to the Okta browser tab. Paste the URL in your clipboard into the text box labeled Audience URI (SP Entity ID). Make sure that the Name ID format drop-down item is set to Transient. Check that the Application username drop-down item is set to Okta username.

Next move to the Attribute Statements (optional) section. This is where you must define the username as well as any other attributes you send to your Docebo Learn platform. To use the Okta username, add user.login in the Name text box, type user.login into the Value box.

Please note: This section is NOT optional for the Docebo configuration, despite being marked as optional in the Okta interface.

If you want to map additional attributes to Docebo from Okta, or use a different field value for the Docebo username, you can add these attributes here as well. To locate these values in Okta, click on the Directory drop down link in the left sidebar menu. Then, press People and in the resulting window click on a username to open their details. Next, click the Profile tab. The attributes are below each attribute name. Below is an example of this page:

Here is how the First Name, Middle Name, Last Name, Department, and Email attributes would be mapped in Okta in the Attribute Statements section. Please note that for user attributes, the attribute name should be preceded by user.. The same concept would apply to other user attributes you wish to map to your Docebo Learn platform:

In the Okta interface, this would look as follows:

Scroll down to the bottom of the screen and press the Next button. On the next screen, select the option I am an Okta Customer adding an Internal App. In the App type section, select the This is an Internal App that we have created checkbox and then press the Finish button.

On the next screen, click the View SAML setup instructions button to view the various items you will need to insert into your Docebo Learn platform.

Copy the value for Identity Provider Issuer to your clipboard.

Apply SAML settings in Docebo

Return to Docebo and navigate to the SAML settings. At the top of the page, check the box to mark the SAML configuration Active and paste the link in your clipboard into the Identity Provider ID field.

Return to Okta and scroll down to the Optional section. Copy all the text in the box labeled Provide the following IDP metadata to your SP provider to your clipboard. This is the Identity Provider Metadata.

Return to your Docebo Platform SAML settings. Paste the Identity Provider Metadata into the XML Metadata field.

Locate the Username Attribute section in the Docebo SAML settings. Input the Okta field name you would like to use as the Docebo username. It is important that this value exactly matches what is in Okta, including capitalization.

Tip: There are edge cases where a different lookup value (Unique Field) may be advantageous. If your configuration necessitates a different lookup value than the Docebo username, you can change the lookup value here.

If you wish to prevent the user from changing their field values that were populated through Okta, select the option to Lock provisioned user fields, meaning that users cannot edit details in their user profiles that have been populated via SAML. If this setting is selected, the fields will be grayed out. As an alternative, you can mark additional user fields Invisible to the User when creating the additional field.

If you wish to map additional attributes from Okta to the Docebo user profile, and you want these attributes to be updated with the current information from Okta each time a user logs into Docebo, select If user exists, update user information. If you do not wish to update information on each user login, do not select If user exists, update user information.

Service provider certificates

Service Provider Certificates are used to sign SAML requests, this is an optional configuration. If you enable this option, the system requires both a public certificate and private key to be uploaded. Generating these certificates is a technical activity. If you do not want to upload Service Provider Certificates, skip to the SSO behavior chapter.

There are several ways to obtain public and private certs, including generating the certificates via the command line using OpenSSL. If you have OpenSSL installed on your machine, the command below should generate self signed certs that are valid for 3 years. There are also many resources available online for generating public and private certificates.

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 1095 -out certificate.pem

Locate the Signature Algorithm section In the Docebo SAML settings. Select SHA-256.

SSO behavior

Locate the SSO Behavior section in the Docebo SAML settings. If you wish to present a Docebo login screen with a button to initiate the authentication process with Okta, select Show standard login page and Show SSO button on login page. If you do not wish to show the Docebo Login page, and wish to redirect the user to Okta when they browse to your Docebo URL, select Automatic redirect to identity provider.

Please note: 

• If some of your users do not exist in Okta, and are expected to log in with native platform credentials, select Show the SSO button on the login page. In this way, Okta users can press the SSO button to sign in via Okta (or click the tile in Okta), and non-Okta users can sign in with their Docebo credentials using the platform's native login form on the sign in page.

For more information see the article General guidance SSO configuration > SSO behavior.

If you have selected the Automatic redirect to identity provider setting, you are able to specify a URL that the user will be directed to when they press Sign Out from the Docebo system. This is an optional setting, if nothing is inserted here, a generic logout screen will be shown to the user. This option is not available if you have selected Show SSO button on the login page.

Logout behavior

Locate the Logout Behavior section In the Docebo SAML settings. If you wish for a user to be logged out of Okta when the user clicks Sign Out from Docebo, select this option.

If you do not wish to enable the Logout Behavior, locate the and press the SAVE CHANGES button in the Docebo SAML settings at the bottom of the page and move on to the Okta Application Assignment section.

Please note: In order for the Logout function to work, OKTA requires that the logout request be signed by Docebo. In order for Docebo to sign requests, you must upload Service Provider Certificates.

If you enabled the Logout Behavior in the previous step, and you have generated and uploaded your Private and Public certificates, go to the SAML settings of your App in Okta and click Show Advanced Settings.

Refer back to the metadata file that you downloaded from Docebo earlier and look for the first XML tag labeled md:SingleLogoutService. The Location for this tag should be a URL. Copy this URL to your clipboard (do not include the quotations). Below the URL to be copied is highlighted, your url will be slightly different as the URL makes reference to your specific Docebo instance.

<?xml version="1.0"?>
  <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" 
entityID="https://academy70.docebosaas.com/lms/index.php">
  <md:SPSSODescriptor 
protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol 
urn:oasis:names:tc:SAML:2.0:protocol">
    <md:SingleLogoutService 
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-logout.php/default-sp"/>
    <md:SingleLogoutService 
Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-logout.php/default-sp"/>
    <md:AssertionConsumerService
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-acs.php/default-sp" index="0"/>
    <md:AssertionConsumerService 
Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml1-acs.php/default-sp" index="1"/>
    <md:AssertionConsumerService 
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-acs.php/default-sp" index="2"/>
    <md:AssertionConsumerService 
Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml1-acs.php/default-sp/artifact" index="3"/>
  </md:SPSSODescriptor>
  <md:ContactPerson contactType="technical">
    <md:GivenName>Administrator</md:GivenName>
    <md:EmailAddress>tech24@docebo.com</md:EmailAddress>
  </md:ContactPerson>
</md:EntityDescriptor>

In your SAML App Advanced Settings, locate the Signature Certificate section. Press the Browse files… button to browse to your public certificate that you generated earlier and upload it.

Next, locate the Allow application to initiate single logout setting and enable it.

Locate the Single Logout URL input field. Paste the link on your clipboard into the field.

Return to the metadata file that you downloaded from Docebo previously. On the second line of the file is a tag labeled entityID. Copy the URL that entityID is equal to (do not include the quotations). An example entityID is highlighted below:

<?xml version="1.0"?>
  <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" 
entityID="https://academy70.docebosaas.com/lms/index.php">
  <md:SPSSODescriptor 
protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol 
urn:oasis:names:tc:SAML:2.0:protocol">
    <md:SingleLogoutService 
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-logout.php/default-sp"/>
    <md:SingleLogoutService 
Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-logout.php/default-sp"/>
    <md:AssertionConsumerService
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-acs.php/default-sp" index="0"/>
    <md:AssertionConsumerService 
Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml1-acs.php/default-sp" index="1"/>
    <md:AssertionConsumerService 
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml2-acs.php/default-sp" index="2"/>
    <md:AssertionConsumerService 
Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01" 
Location="https://academy70.docebosaas.com/lms/index.php?r=SimpleSamlApp/
SimpleSamlApp/modules/saml/sp/saml1-acs.php/default-sp/artifact" index="3"/>
  </md:SPSSODescriptor>
  <md:ContactPerson contactType="technical">
    <md:GivenName>Administrator</md:GivenName>
    <md:EmailAddress>tech24@docebo.com</md:EmailAddress>
  </md:ContactPerson>
</md:EntityDescriptor>

Return to Okta and locate the SP Issuer input field. Paste the link on your clipboard into the field.

Next, scroll down and press the Next button and in the following screen, press the Finish button and on the next page, click View SAML Setup Instructions. Scroll down to the bottom of the page and copy the IDP metadata to your clipboard.

Please note: This step duplicates a previous step but as the logout settings affect the metadata, this data must be reimported to Docebo to reflect the changes made.

Return to Docebo and navigate to the SAML settings. Paste the Identity Provider Metadata into the XML Metadata field.

Locate the and press the SAVE CHANGES button in the Docebo SAML settings at the bottom of the Page.

OKTA application assignment

Return to your App in Okta and click the Assignments tab. Assign yourself or a test user to the application by clicking the Assign button, followed by Assign to People in the dropdown list. After you have assigned a user to the App, you are ready to test Single Sign On.

Testing

If you did not enable user provisioning (the ability for Okta to create users in Docebo) earlier, you will need to create a user in Docebo with a username that matches what Okta will send for the attribute you have designated as the username attribute. If you want to double check what this value will be, go to Okta, click Directory, followed by People and search for your test user. Next, click that User, then click the Profile tab. This will show you the attribute values for the user. For instructions on creating a user in Docebo, refer to Creating and Managing Users in the Docebo Knowledge Base.

If you enabled user provisioning, there is no need to create the user in Docebo prior to testing Single Sign On.

Next, sign out of both the Docebo Learn platform and Okta. Open a new browser tab and navigate to the URL of your Docebo instance. If you are using a custom domain, navigate to your custom domain URL.

If you have enabled the Automatic redirect to identity provider setting, you should be redirected to Okta and presented with a login screen. Enter the user credentials of the user you assigned to the Okta app earlier. After signing into Okta, you will be redirected to Docebo and signed in to the Docebo platform.

If you have not enabled the Show SSO button on the login page setting, on the Docebo login page, click the Sign in with SAML SSO button, which should redirect you to Okta. After signing into Okta, you will be redirected to Docebo and signed in to the Docebo platform.

If you are not mapping any additional attributes or Branch Mapping, and your sign-in attempt was successful, you can skip the rest of the testing section and proceed to the Deployment Section.

If you mapped additional attributes, you should verify that the attributes populated on the Docebo User record when you signed into the platform through Single Sign on with OKTA.

To verify, sign in to Docebo as a Superadmin. Click the Gear Icon in the top right of the page, then click Users near the top left of the page. Search for the Test User you are using to log-in with via Okta, hover your mouse over the user and click the ellipsis menu over on the right side. In the pop up menu, click Edit.

In the slide out menu, confirm that any stock Docebo fields you are mapping to have populated correctly (Mappable stock fields are Username, E-mail, First Name, Last Name)

Click the Additional fields tab at the top of the menu and verify that the Additional Fields you are mapping have populated correctly.

If you have mapped an attribute to the Docebo Branch Name or Branch Code, click the Branches tab at the top of the menu and verify that the user has been assigned to the expected branch.

Deployment

When you are ready to deploy your app to Okta users, Log into Okta and click the Admin button.

In the Admin screen, which may open in a new browser window or tab, click on Applications in the left menu section and press on Applications in the resulting drop-down list. In the resulting window, click the name of your Docebo SAML Integration application.

Click the Assignments tab followed by the Assign button. In the resulting dropdown window select the appropriate choice, depending on whether you wish to assign the application to a person or a group.

Data considerations

If you have enabled user provisioning, It is recommended that you perform a data audit of the user field values in Okta that you will be mapping to Docebo to verify consistency. This is particularly relevant if you are using field values to construct groups in Docebo or assigning users to a particular branch through the SAML app. In some cases, user data in Okta must be cleaned up or normalized in order to ensure that Docebo can expect specific values for group and branch populations.