Embedding the Docebo Flow Launcher in your web page

Introduction

Docebo Flow allows you to start an instance of your Docebo platform on any external web page, as long as you have access to its HTML and JavaScript code.

The Docebo platform instance opens as a pop-up activated either when the user clicks on a button or interacts with an element - such as a link, or a string - on the external web page. When the pop-up opens, the platform instance shows the training content you, as the Superadmin, have selected for the user on the basis of the action he or she is performing, in order to provide the best learning on the fly experience, enriching it with ad hoc training.

Depending on the Docebo Flow configuration, users can be automatically provisioned so that their learning on the flow of work is not an event interrupted by the need to log in.

Docebo Flow is available as a web-based application on desktop and mobile platforms.

The Docebo Flow Launcher allows you to open an instance of your Docebo platform in any external web platform, as long as you have access to its HTML and Javascript code. Find out more on Docebo Flow and the Docebo Flow Launcher in their respective knowledge base articles.

This article is a technical guide on how to embed the Docebo Flow Launcher into your web platform.

Follow the steps listed in this chapter to embed the Docebo Flow app launcher code into your web page.

Step 1

Start by embedding the following JavaScript code in the HTML header of your web page:

<script type=”text/javascript” src=”https://cdn1.dcbstatic.com/flow/kernels/Kernel-latest.bundle.min.js”>

Please note: The domain of the source can change based on the region of the LMS platform to provide better usage performance. Please go on your APP Launcher configuration page to verify the correct link.

Step 2

Docebo Flow uses CSS tokens to allow for the configuration of the Launcher and its contents, therefore the following section must be added to your CSS code:

dcbo-flow-launcher {
}

Step 3

Docebo Flow needs an access token to the Docebo platform in order to show you courses and other modules. To obtain an access token or renew an expired access token before and while using Docebo Flow, you must include and complete the following code snippet in the JavaScript code of your website. This JavaScript function will renew the access token when it expires or will obtain a new one if the token is not provided yet.

function renewToken() {
// insert here the call to your backend to get a new token
}

DFlow.launcher().setTokenProvider(renewToken)

In the renewToken() function, implement the code needed to renew the token by performing an HTTPs request to your backend. This function must return a Promise that resolves with the OAuth2 access token.

In order to make sure that the token will be renewed upon expiration, you have to link a callback to your backend in the setTokenProvider() function before starting the Launcher.

Step 4

Use the following JavaScript events to start the launcher in your web page:

DFlow.launcher().start(
  { 
    domain: <domain>, 
    launcherCode: <launcherCode>, 
    token: "insert here your access token (optional)", 
    language: "your preferred language"
  }
);

Access token retrieval example

As a test, in order to emulate a login, you can attempt an API login with your existing service user using user and password. The returned JSON will include the same data as the OAuth2 authentication method. To do so, perform the following call:

cURL -X POST \
https://yourdomain.docebosaas.com/manage/v1/user/login \
-d '{
  "username": "your-username",
  "password": "your-password"
}'

A positive authentication API call returns a valid authentication token in JSON format, similar to the following:

{
  "access_token": "03807cb390319329bdf6c777d4dfae9c0d3b3c35",
  "expires_in": 3600,
  "token_type": "bearer",
  "scope": null
}

As an option, you can use the Resource Owner Credentials grant type. This authentication method is useful when you own the credentials of every user that will have access to the Docebo Flow instance, but it is not commonly used.

Creating an OAuth2 login with grant type Resource Owner Credential is not part of the Docebo standard provisioning process, you need to activate the API and SSO app, as described in the dedicated Knowledge Base article.

Obtaining a valid access token for users’ authentication

In order to authenticate users with the proper Docebo access token and to renew the tokens when sessions expire, create an OAuth2 API client with JWT bearer connection in with your Docebo platform. As a reference, you can use the current Docebo JSON Web Token (JWT) capability described in the API’s Authentication article of the Docebo Knowledge Base.

Building an integration with JSON Web Token (JWT) authentication

JSON Web Token (JWT) is an open standard (RFC 7519 - opens in a new tab) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret token (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA encryption (from the Introduction to JSON Web Tokens - opens in a new tab).

Docebo strongly recommends using the JWT authentication method to authenticate the users that will access Docebo Flow. This method allows Docebo to receive valid access tokens without transmitting sensitive information such as the client secret (not needed by Docebo).

Signed tokens can verify the integrity of the claims contained within them, while encrypted tokens hide those claims from other parties. When tokens are signed using public/private key pairs, the signature also certifies that only the party holding the private key is the one that signed it. In the case of Docebo Flow, tokens must be signed with your private key.

Best practices

This chapter collects some best practices for embedding Docebo Flow on your web page.

Docebo as Service Provider

When using Docebo Flow App Launchers, remember that Docebo is a Service Provider.
You are in charge of any logic aimed at managing and provisioning users with any supported SSO method, as well as of the adoption of an Identity Provider service.

Docebo can authenticate users only if they already exist in the platform. You are responsible for any synchronization and user provisioning process, such as retrieving Docebo usernames from Identity Providers, creating a new user, etc.

We suggest you make sure that the users provisioned into the platform are the same users who will access your web page. Use the same usernames as the ones used by the users logged into your system to ease the retrieving of the valid Docebo access token.

The following image shows the steps needed to use the App Launcher with an authenticated user in the Docebo platform.

Steps needed to use the App Launcher with an authenticated user in the Docebo platform

Authenticate users in the Docebo Flow App Launcher

The Docebo Flow access control mechanism depends on the presence of a valid access token that is checked every time a user accesses the platform from an App Launcher. The token generation must be done through API before the user navigates the Docebo Flow App Launcher according to the OAuth2 (RFC 6749) validation method.

All of the authentication calls made via APIs should be directed to:

POST https://mydoceboembed.docebosaas.com/oauth2/token

That mechanism can potentially rely on a full set of OAuth2 based grant types to generate a token on behalf of a logged-in user.

Using the JWT Bearer

The most common and suggested authentication method for Docebo Flow requires the usage of a JSON Web Token. This method allows you to receive valid access tokens without transmitting sensitive information such as the client secret, since there is no need for Docebo Flow to know the passwords of your users.

JWT structure for Docebo Users’ authentication

In its compact form, JSON Web Tokens consist of three parts separated by dots (.):

Header
Payload
Signature

Therefore, a JWT typically looks like the following:

xxxxx.yyyyy.zzzzz

The header typically consists of two parts: the token type, which is always JWT, and the signing algorithm in use, such as HMAC SHA256 or RSA. The authentication in Docebo Flow App Launchers only supports the RS256 signature algorithm.

{
  "alg": "RS256",
  "typ": "JWT"
}

The JSON is Base64URL encoded to form the first part of the JWT. The second part of the token is the payload including the claims. Claims are statements about the user in the authentication process. Docebo uses registered claims only (for further information on registered, public, and private claims see JWT Claims - opens in a new tab)

To proceed with authentication you have to provide the following claims, correctly valued:

“Issuer” Claim (iss): This claim must include the Client ID. This value can be configured through the proper field in your OAuth2 Application in the Admin section.
“Subject” Claim (sub): This claim must contain the username of the user to log in. The username must be the one of the user registered in the Docebo platform, not the username of the user in your system. Make sure you are providing the alphanumeric username field, not the numerical user_id.
“Audience” Claim (aud): This claim must contain the SaaS domain URL of the Docebo platform you want to authenticate in, with the following format:
myplatform.docebosaas.com (make sure you remove the protocol from the URL).
“Issued At” Claim (iat): This claim must contain the JSON Web Token creation date in Unix timestamp format (for further details, see unixtimestamp.com)
“Expiration Time” Claim (exp): This claim must contain the JSON Web Token creation date in Unix timestamp format (see above)

The token payload will look like this:

{
  "iss": "ACMEDoceboEmbed",
  "sub": "your-users-username",
  "aud": "mydoceboembed.docebosaas.com",
  "iat": "1510649850",
  "exp": "2554329600"
}

The payload is then Base64URL encoded, in order to form the second part of the JSON Web Token. To create the signature part, take the encoded header, the encoded payload, the private key you provided, and sign that.

As an example, if you are using the HMAC SHA256 algorithm, the signature will be created as follows:

HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
secret)

The signature is used to make sure that the message did not go through any changes along the way, and to validate the identity of the JWT sender. When tokens are signed with a private key, the signature also verifies the identity of the JTW sender.

The final output is three Base64-URL strings separated by dots.

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJBQ01FRG9jZWJvRW1iZWQi
LCJzdWIiOiJ5b3VyLXVzZXJzLXVzZXJuYW1lIiwiYXVkIjoibXlkb2NlYm9lbWJlZC5kb
2NlYm9zYWFzLmNvbSIsImlhdCI6IjE1MTA2NDk4NTAiLCJleHAiOiIyNTU0MzI5NjAwIn
0.DTElTpxmE-qXQ9iAsjI2bWxftw8dZlrKVusZ4Rx0u3qpjCjNwoD1UJiG3CARauSxtGU
fwvshfpBijT8krPO39XThnMC72LQiHBlgECNq7QGGdHt_Qz17ly0iDaK9ibfqgsh3uCyL
vjow39qzZZiicg0KO5rmW0j_Y60iyEb09Q4hQNFKk4xW9cdAX3GyxQ8ESL-NXYG6SanBD
eZpkOuL0uecvpMASkh8Of_zRZKNQE4rnjnZ6s9sPxV3vXroFcFy6wR4mgNSEJuY_NK0Lv
6x9uKiZX0oFKGsORhL7lp5RKq4Q9zfJGGfYzsp38aHstVUXaBCDoZXtoDeCVCl-yTzsA

Creating and Testing the JWT

Since the structure of JWT is based on well-known standards, you don’t need to write specific code to create the token. You can rely on existing and well-established libraries.

An excellent resource is jwt.io (link opens in a new tab). The library (link opens in a new tab) section offers a wide selection of open-source libraries for various programming languages including .NET, Phyton, Perl, Java, Javascript (and Node.JS), PHP and many others.

You can verify the correct functioning of the token with the debugger tool made available by the site.

Using JWT to Obtain an Access Token

Besides generating a valid JWT, you have to exchange the JWT with a normal access token in order to access Docebo through a Docebo Flow App Launcher. To so, you need an API call:

POST https://mydoceboembed.docebosaas.com/oauth2/token

The call must have two attributes (in form data):

grant_type - it must have this string as a value:
- urn:ietf:params:oauth:grant-type:jwt-bearer
assertion - it must contain the encoded JWT token

Here is a cURL example:

cURL --request POST \
  --URL https://mydoceboembed.docebosaas.com/oauth2/token \
  --form grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  --form assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJBQ01F
RG9jZWJvRW1iZWQiLCJzdWIiOiJ5b3VyLXVzZXJzLXVzZXJuYW1lIiwiYXVkIjoibXlkb2Nl
Ym9lbWJlZC5kb2NlYm9zYWFzLmNvbSIsImlhdCI6IjE1MTA2NDk4NTAiLCJleHAiOiIyNTU0
MzI5NjAwIn0.DTElTpxmE-qXQ9iAsjI2bWxftw8dZlrKVusZ4Rx0u3qpjCjNwoD1UJiG3CAR
auSxtGUfwvshfpBijT8krPO39XThnMC72LQiHBlgECNq7QGGdHt_Qz17ly0iDaK9ibfqgsh3
uCyLvjow39qzZZiicg0KO5rmW0j_Y60iyEb09Q4hQNFKk4xW9cdAX3GyxQ8ESL-NXYG6SanB
DeZpkOuL0uecvpMASkh8Of_zRZKNQE4rnjnZ6s9sPxV3vXroFcFy6wR4mgNSEJuY_NK0Lv6x
9uKiZX0oFKGsORhL7lp5RKq4Q9zfJGGfYzsp38aHstVUXaBCDoZXtoDeCVCl-yTzsA

As stated at the beginning of this document, a positive authentication API call returns a valid authentication token in JSON format, similar to the following:

{
  "access_token": "03807cb390319329bdf6c777d4dfae9c0d3b3c35",
  "expires_in": 3600,
  "token_type": "bearer",
  "scope": null
}

Docebo Help

How can we help?

Introduction