Avant de commencer
Vous devez avoir ces informations :
- La paire Id-Key de votre application (disons « appID » et « appKey », mais ils ne ressembleront pas à cela)
- Le domaine de votre service back-end (quel LMS appelez-vous)
- Le point de rappel de votre application/service où le LMS peut envoyer Paires Id utilisateur-Clé lorsque vous les demandez
Création du compte de service et collecte des jetons d’utilisateur
Votre application devra s’exécuter avec un compte de service ou un autre compte doté de privilèges suffisants pour effectuer les actions que vous devez effectuer avec les API. Ainsi, la première étape consiste à créer un compte dans l’environnement d’apprentissage avec des privilèges suffisants pour passer les appels d’API que vous devez passer.
Une fois que vous avez créé un compte de service :
- Vous devez récolter manuellement les jetons utilisateur à l’aide d’un utilitaire tel que l’outil de test d’API () pour vous authentifier auprès de votre LMS.
- Stockez ces clés en toute sécurité et configurez votre LMS pour vous assurer que les jetons utilisateur ont une longue durée de vie. De nombreux systèmes ont un délai d’attente symbolique de 30 jours, mais lorsqu’une intégration sans tête est en place comme celle que vous proposez, c’est souvent une bonne idée de rendre le délai d’attente infini. Vous pouvez contacter le support Desire2Learn pour vérifier la valeur de délai d’attente pour les jetons utilisateur.
Remarque : les « jetons d’utilisateur » ci-dessus ne signifient pas le délai d’attente réglé par l’intermédiaire du d2l. Paramètre du serveur SessionTimeout. Au contraire, ceci est réglé par l’intermédiaire du d2l. Paramètre Security.Api.TokenTimeout.
Pour clarifier davantage :
- Le d2l. La variable de configuration de SessionTimeout fait référence à la période de délai d’attente de la session Web (c’est-à-dire combien de temps quelqu’un peut être inactif avant que l’interface utilisateur Web LMS ne chronomètre et invite l’utilisateur à se reconnecter). Ce délai d’attente est souvent réglé à un intervalle de plusieurs minutes à une heure.
- Le d2l. La variable de configuration Security.Api.TokenTimeout fait référence à la période de délai d’attente de la paire d’id utilisateur\clé associée au processus d’authentification valence. En d’autres termes, ces jetons sont la valeur x_b et la base de la valeur x_d qui sont envoyés en tant que paramètres de requête sur chaque appel d’API pour identifier l’utilisateur. Ce délai d’attente est souvent placé à un intervalle de plusieurs jours, ou pourrait être placé pour ne jamais le délai d’attente. Dans ce dernier cas, la paire id utilisateur\clé ne peut être invalidée qu’en modifiant le mot de passe de l’utilisateur ou en révoquant explicitement l’accès à l’application. Une fois que la paire d’ID utilisateur\clé devient non valide, l’application devra reprendre le processus d’authentification pour recevoir une nouvelle paire d’ID utilisateur\clé pour signer les appels d’API.
Créer un contexte d’application
- Construire un contexte d’application avec D2LAppContext( « appID », « appKey », « ») ; cela façonne un contexte d’application que vous pouvez ensuite utiliser pour effectuer la demande d’extraction d’une paire Id utilisateur-Clé à partir du LMS
- authURL = DAC.createWebUrlForAuthentication( nouveau URI(« »)) ; cela rend le « authURL », vous devez diriger un conteneur Web (le navigateur de l’utilisateur) vers cette URL : qui demande au LMS de renvoyer la paire Id utilisateur-Clé pour la session utilisateur qui s’établira à l’intérieur du conteneur Web demandeur.
Le LMS enverra la paire d’id utilisateur-clé en réorientant retour à avec la paire Id utilisateur-Clé attachée en tant que paramètres de requête sur l’URL de redirection. Appelons cela complet rediriger l’URL 'fullRedirectUrl'.
Créer un contexte utilisateur
- Tu le peux soit créer un contexte utilisateur en utilisant fullRedirectUrl: DAC.createUserContext( fullRedirectUrl )
- OU, vous pouvez extraire la paire Id utilisateur-Clé de fullRedirectUrl (disons 'userID' et 'userKey', mais ils auront l’air différents), et utiliser : DAC.createUserContext( « userID », « userKey » )
Passer des appels
- Vous pouvez maintenant utiliser votre contexte d’utilisateur, CIC, pour faire des appels : DUC.createAuthenticatedUri( « /d2l/api/lp/1.3/users/whoami », « GET »)
Remarque : qu’ici vous fournissez l’itinéraire API uniquement, plus la méthode HTTP (majuscules) ; assurez-vous d’utiliser un itinéraire dans un contrat API que votre LMS back-end prend en charge - ici, nous faisons l’appel whoami du contrat API v1.3, mais votre LMS peut ne pas prendre en charge ce contrat (ou il peut prendre en charge un plus récent).
Dépannage
Question : Pour être clair, je prends le "... ou" route mentionné ci-dessus, en extrayant les valeurs userID et userKey de apitesttool. desire2learnvalence.com, puis en faisant createUserContext en utilisant ces valeurs (ainsi que le nom d’hôte D2L, le port, etc --- la version à 6 paramètres de cette fonction).
Je reçois un contexte de retour de cette méthode et quand je l’utilise pour faire un appel d’API, le service renvoie un 403 « Jeton non valide. »
Réponse : Si votre application n’était pas connue du LMS (c’est-à-dire qu’il ne s’agit pas d’un ID d’application activé), vous obtiendriez une erreur légèrement différente. Cela nous dit que soit vous ne créez pas de Sig d’application valide dans votre éventuel appel d’API (ce qui signifie probablement que votre clé d’application ne convient pas à votre ID d’application), ou la clé d’identification utilisateur que vous utilisez n’est en quelque sorte pas utile.
Nous vous recommandons fortement de passer à travers la promenade à travers sur le Documents du SDK client Python même si vous n’avez pas l’intention d’utiliser Python à long terme. Vous pouvez passer par ce processus de manière interactive et étape par étape, et ainsi avoir un contrôle plus direct sur ce qui se passe à chaque étape du processus pour voir ce qui se passe. Avec une application d’entreprise construite à partir de C # ou Java, vous êtes réduit aux techniques de débogage standard pour vous frayer un chemin dans le flux de travail - qui fonctionnent également bien : cependant, un shell interactif vous permet d’exécuter chaque étape au fur et à mesure et d’inspecter les résultats.
Pour commencer avec le SDK python comme dans cette procédure pas à pas, vous avez besoin de :
- Pour avoir une installation Python, et il est utile d’avoir le paquet 'pip' installé pour faire l’installation du module python
- Pour avoir le module python « demandes » installé (que pip devrait trouver automagiquement)
- Pour avoir le module python 'd2lvalence' installé (quel pip devrait trouver automagiquement)
Question : Je suis allé regarder la page d’auth Python que vous avez référencée, mais je suis confus. Cette page me conseille d’aller dans le navigateur et d’attraper l’URL de redirection après avoir obtenu le résultat de createUrlForAuthentication (en utilisant le format php pour la fonction).
Réponse :
La façon dont le modèle fonctionne à un niveau élevé est comme un modèle auth à trois pattes :
- Vous avez un vrai utilisateur avec un navigateur
- Vous disposez d’un service ou d’une application tiers que l’utilisateur peut visiter (généralement) qui souhaite effectuer des appels API Valence au nom de cet utilisateur
- Vous avez le LMS back-end
Lorsque l’utilisateur réel visite l’application 3ème partie, avant de pouvoir passer des appels API, il doit demander au LMS une paire Id utilisateur-Clé pour aller avec sa paire Id-Clé d’application afin qu’il puisse faire des appels API au nom de l’utilisateur. Pour ce faire, il redirige le navigateur de l’utilisateur vers le « chemin de connexion » du LMS pour s’assurer que le LMS « sait » qui est l’utilisateur / navigateur :
- Si le navigateur de l’utilisateur a déjà une session Web avec LMS, le LMS peut dire « Je sais qui est l’utilisateur » et envoyer la bonne paire Id utilisateur-Clé à l’application 3ème partie.
- Si le navigateur de l’utilisateur n’a pas encore de session, le LMS peut chercher à authentifier l’utilisateur en utilisant la manière standard pour ce LMS ; ENSUITE, il peut renvoyer la bonne paire d’id utilisateur-clé à l’application 3rd party (Notez que, dans les deux cas, la paire Id utilisateur-Clé est générée spécifiquement pour CET utilisateur et CETTE application : elle n’est transférable à aucune autre paire Id-Clé d’application.)
Ce système d’ath à trois pattes est logique dans le cas où vous avez vraiment trois parties distinctes. Dans des cas comme le vôtre, où vous souhaitez écrire une application de service informatique (sans tête) qui n’a pas de véritable « utilisateur en cours d’exploitation avec leur navigateur Web », nous vous recommandons généralement de créer un compte de service - un objectif spécial, « utilisateur » et « rôle » qui n’est utilisé que pour votre application de service.
Dans ce cas, vous devez avoir un moyen de passer par le processus auth ci-dessus chaque fois que vous avez besoin d’une paire id utilisateur-clé valide pour ce service « utilisateur ». Il existe un tas de façons de le faire, mais elles impliquent toutes d’avoir (à un moment donné) un vrai utilisateur avec un vrai navigateur se lever et jouer le rôle de cette troisième étape dans le processus d’entère.
En règle générale, ce que vous faites est soit d’utiliser une version hébergée localement de l’un de nos échantillons simples, soit notre « outil de test d’API » en ligne (https://apitesttool. desire2learnvalence.com/), ou une session Python interactive avec notre SDK Python (comme dans la procédure pas à pas auth que j’ai indiquée). En règle générale, pour une meilleure sécurité, nous vous recommandons de faire ce processus dans un environnement sécurisé, de sorte que l’outil de test d’API n’est peut-être pas la meilleure solution, surtout si vous n’allez pas vous connecter à HTTPS, car il est assis sur Internet. Cependant, si vous utilisez HTTPS pour le connecter à votre LMS, il est probablement suffisamment sûr.
Pour le processus de « collecte d’une paire d’id utilisateur-clé », vous devez utiliser vos propres informations d’identification id-clé d’application (c’est-à-dire, la paire que vous avez reçue pour l’application / service que vous écrivez).
Si vous le faites de manière interactive, vous créez un contexte d’application avec ces informations d’identification. Si vous utilisez un exemple ou l’outil en ligne, vous fournissez votre propre paire App Id-Key comme celles à utiliser (pas celles par défaut dans le formulaire : il s’agit d’un ensemble unique de clés publiques à des fins de démonstration). Vous devez fournir le nom d’hôte de votre LMS et le port à appeler. Ensuite, vous passez par le « processus d’entère » :
- Si vous utilisez une session interactive avec le SDK Python, vous créez une « URL d’authentification » que vous allez couper et coller dans votre navigateur... pour ce faire, vous devez également fournir une « URL de rappel » indiquant au LMS où envoyer la clé d’id utilisateur - nous suggérons localhost car cela retournera à l’ordinateur où se trouve votre navigateur, et probablement votre navigateur se plaindra qu’il ne peut pas trouver l’URL, mais vous pouvez ensuite copier l’URL terminée hors de la barre d’adresse.
- Si vous utilisez l’exemple ou l’outil en ligne, l'«URL de rappel » vous est cachée - le formulaire le fournit automatiquement : la paire Id utilisateur-Clé sera renvoyée au serveur Web exécutant l’exemple / outil en ligne.
Lors de la transmission de la paire Id utilisateur-Clé, le LMS les mettra comme paramètres de requête sur cette « URL de rappel » que vous avez fournie dans la demande que vous venez d’envoyer.
- Si vous utilisez l’outil en ligne ou un échantillon, l’outil/l’échantillon doit décomposer automatiquement cette URL de rappel, éplucher les informations d’identification et vous les montrer.
- Si vous utilisez une session Python interactive, le LMS redirigera vers « localhost » et alignera la paire Id utilisateur-Clé dans les paramètres de requête. Copiez l’URL entière de la barre d’adresse du navigateur et répercutez-la dans votre session Python pour créer le « contexte utilisateur » - cela décollera les clés d’identification utilisateur de cet URI de résultat et créera un contexte utilisateur que vous pouvez utiliser pour passer des appels API de manière interactive ... vous pouvez également l’inspecter pour voir ce que sont la paire d’id utilisateur-clé, les enregistrer sur le disque, et ainsi de suite.
Dans tous les cas, vous n’avez pas réussi à « rassembler une paire Id utilisateur-Clé » pour VOTRE compte de service pour aller avec VOTRE Id-Clé d’application. Vous pouvez le mettre en cache dans un endroit sûr accessible à votre script/application d’administration (comme dans un fichier de configuration). Nous vous recommandons fortement de traiter la paire Id-Clé d’application de votre application et toutes les clés d’identification d’utilisateur qui l’accompagnent comme des informations très sensibles - avec ces jetons N’IMPORTE QUI peut faire un appel à votre LMS prétendant être votre application en tant qu’utilisateur valide, de sorte que vous souhaitez les mettre dans un endroit sûr visible uniquement par un petit nombre de personnes et pour le script / l’application qui doit les utiliser.
Chaque fois que le mot de passe de ce compte de service change, vous devrez refaire ce processus pour rassembler une nouvelle paire Id utilisateur-Clé. Si vos LMS ont des jetons d’API configurés pour expirer dans un temps fixe, vous devrez également refaire ce processus lorsque ce temps s’écoulera. Par défaut, ce délai d’expiration est défini sur « indéfini » et les jetons de clé d’identification utilisateur expirent uniquement lorsque le mot de passe de l’utilisateur change ou que l’administrateur du site refuse l’accès aux applications tierces pour cet utilisateur.
Pour un autre point d’explication, vous pouvez voir ce sujet sur notre blog de développeur : Prise en main de l’authentification de clé d’id d’application. Il a plusieurs années, mais le matériel est toujours vrai, et les diagrammes sont différents de ceux qui apparaissent dans nos documents en ligne, de sorte que le contraste peut aider à obtenir une image plus ronde.https ://d2l.someUniversity.eduhttps ://yourServer.org/authCallback
https://apitesttool.desire2learnvalence.com/
https://d2l.someUniversity.eduhttps://yourServer.org/authCallbackhttps://yourServer.org/authCallback