Authentification
Les API Docebo utilisent le framework OAuth 2.0 dans la plupart des scénarios impliquant des services tiers, y compris l’authentification et l’autorisation pour les serveurs web, et les applications installées et côté client. Les identifiants des applications OAuth 2.0 peuvent être obtenus sur la page des paramètres de l’application API et SSO de Docebo. Pour plus d’informations, veuillez consulter notre article sur le sujet.
Votre application client demandera un jeton (token) d'accès au LMS, l’extraira de la réponse, et l’enverra à chaque API REST que vous souhaitez accéder.
Activation et configuration de l'application API et SSO de Docebo
Commencez par activer et configurer l’application API et SSO sur votre plateforme Docebo. Pour découvrir comment configurer correctement l’application et obtenir vos identifiants OAuth 2.0, veuillez consulter l’article Activer et gérer l’application API et SSO.
Obtenir un jeton d’accès
Pour accéder aux données privées de la plateforme Docebo Learn per l’intermédiaire d’une API Docebo, votre application doit obtenir un jeton (token) lui accordant l’accès à la ressource REST concernée. Un seul jeton d’accès peut accéder à plusieurs API. Le paramètre scope
contrôle l’ensemble des ressources et des opérations autorisées par ce jeton.
Pour obtenir un jeton d'accès, vous devrez effectuer un appel vers l’endpoint concerné. Veuillez noter que le comportement des appels d’API ci-dessous dépendra du niveau de l’utilisateur utilisé pour obtenir le jeton d’accès, en fonction des autorisations définies sur la plateforme.
https://<votresousdomaine.docebosaas.com>/oauth2/token
Pour des informations sur le token OAuth2 et sur les paramètres à inclure dans les requêtes ci-dessous, consultez la documentation officielle OAuth2 (s'ouvre dans un nouvel onglet).
Utiliser le type d’autorisation Resource Owner Password Credentials
Voici un exemple d’appel avec le type d’autorisation défini sur Resource Owner Password Credentials (identifiants de mot de passe du propriétaire de la ressource) :
curl -X POST https://<votresousdomaine.docebosaas.com>/oauth2/token \
-F client_id=<votre_id_client> \
-F client_secret=<votre_secret_client> \
-F grant_type=password \
-F scope=api \
-F username=<votre_nomdutilisateur> \
-F password=<votre_motdepasse>
Réponse :
{
"access_token": "87b567fa3de847fb3adef9492b294bb83f8cd266",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "api",
"refresh_token":"7db6e6a331223fa0473cfcdf62eb8fec26407a5b"
}
Utiliser le type d’autorisation Client Credentials
Voici un exemple d’appel avec le type d’autorisation défini sur Client Credentials (identifiants client) :
curl -X POST https://<votresousdomaine.docebosaas.com>/oauth2/token \
-F client_id=My-Client-Name \
-F client_secret=ed8c18b099c1f9b8714aaef87001fa3de3a7183d \
-F grant_type=client_credentials \
-F scope=api</votresousdomaine.docebosaas.com>
Réponse :
}
"access_token": "87b567fa3de847fb3adef9492b294bb83f8cd266",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "api"
}
À noter : avec les nouvelles API 7.0, qui se trouvent à l’adresse
https://VOTRELMS.docebosaas.com/api-browser/
, le système ne peut fonctionner correctement sans une autorisation spécifique de l’utilisateur. Vous ne pourrez donc pas utiliser les informations d’identification du client pour appeler ce type d’API.
Utiliser le type d’autorisation Authorization code + Implicit
Si votre application utilise le type d’autorisation Authorization Code, vous devrez utiliser l’URL suivante pour lancer le flux d'autorisation :
https://<votresousdomaine.docebosaas.com>/oauth2/authorize
Utiliser le type d’autorisation JWT Bearer
JSON Web Token est une méthode ouverte et standard (RFC 7519) permettant de transmettre des informations (ou « revendications ») de manière sécurisée entre deux parties. Pour en savoir plus, veuillez consulter la documentation sur la norme RFC-7519 (s’ouvre dans un nouvel onglet). Vous pouvez utiliser la technologie JWT pour obtenir un token permettant d’accéder aux API Docebo.
Vous avez également la possibilité de générer un jeton JWT avec la méthode de votre choix. Quelques exemples, ainsi que des bibliothèques pour de nombreux langages de programmation, sont disponibles sur le site jwt.io (s'ouvre dans un nouvel onglet).
Pour créer un JSON WEB Token utilisable pour s’authentifier sur la plateforme Docebo, vous devez paramétrer l’algorithme de signature sur RS256 et téléverser votre clé publique sur l’application API et SSO de votre plateforme après avoir sélectionné le type d’autorisation JTW Bearer. Voici un exemple de clé publique :
-----BEGIN PUBLIC KEY-----
MIGeMA0GCSqGSIb3DQEBAQUAA4GMADCBiAKBgGOrtjv/oPcaWIQL7h3DwvGbWFhH
fAIP02pPPw1Cp8h0SUkmGAWUGKCNH2WuIeNxPlRZKmW86aivknrRtEN3QW6eEsFZ
ZSIKVmUPekKrSpvYmYwkTCnwCb4gpDu1ZPEde8VXhQjLRl7ielUktzzbXW7v1HmI
fDASHvMvIl4kwGA/AgMBAAE=
-----END PUBLIC KEY-----
Les informations suivantes sont nécessaires pour permettre au LMS d’authentifier l’utilisateur :
-
iss
(revendication de l’émetteur) Doit contenir l’ID client configuré sur la plateforme Docebo Learn pour l’authentification de type SSO.
-
sub
(revendication du sujet) Doit contenir le nom d’utilisateur que vous souhaitez utiliser pour vous connecter à la plateforme Docebo Learn.
-
aud
(revendication de l’audience) Doit contenir le nom d’hôte de la plateforme Docebo Learn (sans le protocole) sur laquelle vous souhaitez vous authentifier.
-
iat
(revendication de la date d’émission) Doit contenir la date de création du jeton horodatée au format Unix.
-
exp
(revendication du délai d'expiration) Doit contenir la date d’expiration du jeton horodatée au format Unix.
La charge utile du jeton ressemblera donc à ceci :
{
"alg": "RS256",
"typ": "JWT"
}
{
"iss": "<votre_id_client>",
"sub": "<nomdutilisateur_docebo>",
"aud": "<votresousdomaine.docebosaas.com>",
"iat": "1510649850",
"exp": "2554329600"
}
Une fois le jeton signé avec votre clé privée, vous obtiendrez un token JWT chiffré prêt à être envoyé à des fins d’authentification. Un jeton JWT chiffré se présente comme suit :
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJjbGllbnRfaWRfaGVyZSIsInN1YiI6
InVzZXJuYW1lX2hlcmUiLCJhdWQiOiJ5b3VybG1zLmRvY2Vib3NhYXMuY29tIiwiaWF0IjoiMTUxM
DY0OTg1MCIsImV4cCI6IjI1NTQzMjk2MDAifQ.mrA_k6OClsczj9kEz_jeGZxlusCmzOJWLyDGEp5
A3BttCBna9aKP2_AqCaiwhntjrQ9L6NBEH9oxHr4pM2G9tyeSEGxD0VLVe3CoDljzMgvMdyyK8HP4
0QtALCYEuVF2BIpS8Mz2KhvysKhzVJR71suwaAYnR0I7G8_kAlUR9Ck
Vous pouvez ensuite envoyer les données à l’endpoint d’authentification. Voici un exemple d’appel avec le type d’autorisation défini sur JWT Bearer :
curl -X POST
https://<votresousdomaine.docebosaas.com>/oauth2/token \
-F grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
-F scope=api \
-F assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJEb2NlYm9PRU0iLCJ\
zdWIiOiJyaWNjYXJkby5nYWxpbWJlcnRpQGRvY2Viby5jb20iLCJhdWQiOiJyZ2FsaW1iZXJ0aS\
5kb2NlYm9zYWFzLmNvbSIsImlhdCI6IjE1MTA2NDk4NTAiLCJleHAiOiIyNTU0MzI5NjAwIn0.n\
0Sr0Cy3wjE7C-TqJLTi1JfZjnWnXcKoCidCtz4o8HsaHI0LomM5Ln3gWOqJXq5EI67yDr9L_EwA\
44-_lFKVjV8FAmUU72ZU6indDXP7SaCMEmqQu5tbo9AnW_RKHGoAXPWspH95iZe_VaM0SFjmHbo\
ZXGgPmEt3aNfhaJBBzIcLuk1EIcGZEqtN4ENVp_MREtCMrFg3yMyx47dcf0rmBvizkmthTW1so8\
TG7OXgTfNR0tzPNAOPGbRqciSgfcBNb_ftalW0gE3unAnXpfqMD-8gcUq-c43DfTOiCeNm-ZBLm\
rVoKeUXshyDjf0JOrP8kReIQ9mWIyI0-gvh5-UMVQ
Réponse :
{
"access_token": "87b567fa3de672fb3adef9492b294bb83f8cd266",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "api"
}
Envoyer le token d’accès à une API
Après avoir obtenu un jeton d’accès, votre application doit le fournir à chaque appel de l’API Docebo dans l’en-tête d’autorisation HTTP, sous le format suivant :
Bearer <jeton_daccès>
Exemple :
curl -X GET https://<votresousdomaine.docebosaas.com>/learn/v1/courses \
-H 'Authorization: Bearer 2af6ac532cfef197b00f69639aeeef86621d1975'
Actualiser le jeton d’accès
La durée de vie des tokens est limitée à 14 jours. Votre application peut en obtenir un nouveau en utilisant le Token Endpoint si elle a besoin d’accéder à une API Docebo au-delà de la durée de vie d’un jeton. L’utilisation d’un jeton d’actualisation permet à votre application d’obtenir de nouveaux jetons d’accès.
Veillez à suivre les lignes directrices de la documentation officielle d’OAuth2 (s’ouvre dans un nouvel onglet) en ce qui concerne l’utilisation et le stockage en toute sécurité d’un jeton d’actualisation .
Envoyer le jeton d’accès pour l’authentification unique
Après avoir obtenu un jeton d’accès, votre application doit l’insérer dans un format d’URL spécifique pour que l’authentification unique puisse être prise en charge :
https://<VOTRELMS>.docebosaas.com/learn;type=oauth2_response;access_token=<jeton>;expires_in=4000;token_type=bearer;scope=api
À noter : si vous utilisez un Domaine personnalisé, remplacez
VOTRELMS.docebosaas.com
par l’URL adéquate.