Adding the embedded learning launcher to your web page

Introduction

Embedded learning 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 launcher 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 or it is embedded as a widget within the page. 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.

Embedded learning is available as a web-based application on desktop and mobile platforms.

The 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 embedded learning and the embedded learning launcher in their respective knowledge base articles.

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

Embedding the launcher in your web page

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

Step 1

From the Navigation menu, find the Configuration (spanner icon), then select Additional packages and click on  Embedded learning. In the list of launchers, select the one you wish to embed and in the General tab, make a note of the correct embed link located in the Implementation code section. Next, embed the following JavaScript code in the HTML header of your web page, replacing kernel-link with the embed link you noted in your launcher configuration page.

<script type=”text/javascript” src=”kernel-link”>

Step 2

Embedded learning 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

Embedded learning 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 embedded learning, 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 embedded learning 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 Introduction to Docebo APIs of the Docebo Knowledge Base.

Building an integration with JSON Web Token (JWT) authentication

Background: 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 embedded learning. 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 embedded learning, tokens must be signed with your private key.

Best practices

This chapter collects some best practices for adding embedded learning to your web page.

Docebo as service provider

When using embedded learning 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 launcher with an authenticated user in the Docebo platform.

Authenticate users in the embedded learning launcher

The embedded learning access control mechanism depends on the presence of a valid access token that is checked every time a user accesses the platform from a launcher. The token generation must be done through API before the user navigates the 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 embedded learning 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 embedded learning 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 the launcher 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:

myplatform.docebosaas.com

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 (opens in a new tab). The library (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 Embedded learning 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):

urn:ietf:params:oauth:grant-type:jwt-bearer

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
}