Voordat je aan de slag gaat
U hebt de volgende informatie nodig:
- Het Id-Key-paar van uw toepassing (laten we zeggen 'appID' en 'appKey', maar zo zien ze er niet uit)
- Het domein voor uw back-endservice (welk LMS u belt)
- Het callback-punt voor uw app/service waar het LMS kan Verzenden Gebruikers-ID-sleutelparen wanneer u ze aanvraagt
Het aanmaken van het serviceaccount en het verzamelen van gebruikerstokens
Uw app moet worden uitgevoerd met een serviceaccount of een ander account met voldoende bevoegdheden om de acties uit te voeren die u met de API's moet uitvoeren. De eerste stap is dus om in de Leeromgeving een account aan te maken met voldoende rechten om de API-aanroepen te doen die je moet maken.
Nadat u een Serviceaccount heeft aangemaakt, gebeurt het volgende:
- U moet de gebruikerstokens handmatig verzamelen met behulp van een hulpprogramma zoals de API Test Tool () om te verifiëren met uw LMS.
- Bewaar die sleutels veilig en configureer uw LMS om ervoor te zorgen dat de gebruikerstokens een lange levensduur hebben. Veel systemen hebben een token timeout van 30 dagen, maar wanneer er een headless integratie is zoals degene die u voorstelt, is het vaak een goed idee om de time-out oneindig te maken. U kunt contact opnemen met Desire2Learn Support om de time-outwaarde voor de gebruikerstokens te verifiëren.
Let op: de "user tokens" hierboven betekenen niet de time-out die via de d2l is ingesteld. SessionTimeout-serverinstelling. In plaats daarvan wordt dit ingesteld via de d2l. Security.Api.TokenTimeout-instelling.
Ter verduidelijking:
- De d2l. De configuratievariabele SessionTimeout verwijst naar de time-outperiode van de websessie (d.w.z. hoe lang iemand inactief kan zijn voordat er een time-out optreedt in de webinterface van het LMS en de gebruiker wordt gevraagd opnieuw in te loggen). Deze time-out wordt vaak ingesteld op een interval van enkele minuten tot een uur.
- De d2l. De configuratievariabele Security.Api.TokenTimeout verwijst naar de time-outperiode van het gebruikers-id\sleutelpaar dat is gekoppeld aan het Valence-verificatieproces. Anders gezegd, deze tokens zijn de x_b waarde en de basis voor de x_d waarde die als queryparameters bij elke API-aanroep worden verzonden om de gebruiker te identificeren. Deze time-out wordt vaak ingesteld op een interval van enkele dagen, of kan worden ingesteld op nooit time-out. In het laatste geval kan het gebruikers-id\sleutelpaar alleen ongeldig worden gemaakt door het wachtwoord van de gebruiker te wijzigen of de toegang tot de app expliciet in te trekken. Zodra het gebruikers-id\key-paar ongeldig wordt, moet de app het verificatieproces opnieuw starten om een nieuw gebruikers-id\key-paar te ontvangen om API-aanroepen te ondertekenen.
Een app-context bouwen
- Construeer een app-context met D2LAppContext( "appID", "appKey", ""); dit vormt een app-context die u vervolgens kunt gebruiken om het verzoek in te dienen om een gebruikers-ID-sleutelpaar uit het LMS op te halen
- authURL = DAC.createWebUrlForAuthentication( nieuwe URI("")); dit maakt de "authURL", u moet een web-container (de browser van de gebruiker) naar deze URL leiden: die het LMS vraagt om het User Id-Key-paar terug te sturen voor de gebruikerssessie die in de aanvragende webcontainer tot stand zal worden gebracht.
Het LMS verzendt het gebruikers-ID-sleutelpaar door het om te leiden Terug naar met het gebruikers-ID-sleutelpaar dat als queryparameters aan de omleidings-URL is gekoppeld. Laten we dit noemen vol omleidings-URL 'volledige omleidingsURL'.
Bouw een gebruikerscontext op
- U kunt hetzij Bouw een gebruikerscontext met behulp van volledige omleidingsURL: DAC.createUserContext( fullRedirectUrl )
- OF, kunt u het User Id-Key-paar extraheren uit fullRedirectUrl (laten we zeggen 'userID' en 'userKey', maar ze zien er anders uit) en gebruiken: DAC.createUserContext( "userID", "userKey" )
Bellen
- U kunt nu uw gebruikerscontext, DUC, gebruiken om aanroepen te maken: DUC.createAuthenticatedUri( "/d2l/api/lp/1.3/users/whoami", "GET")
Notitie: dat je hier alleen de API-route opgeeft, plus de HTTP-methode (hoofdletters); zorg ervoor dat je een route gebruikt in een API-contract dat je back-end LMS ondersteunt -- hier maken we de whoami-aanroep van het v1.3 API-contract, maar je LMS ondersteunt dat contract mogelijk niet (of het kan een recenter contract ondersteunen).
Probleemoplossing
Vraag: Voor alle duidelijkheid, ik neem de "... of" hierboven genoemde route, door de waarden userID en userKey te extraheren uit apitesttool. desire2learnvalence.comen voer vervolgens createUserContext uit met behulp van die waarden (samen met de D2L-hostnaam, poort, enz. --- de 6-parameterversie van die functie).
Ik krijg een context terug van die methode en wanneer ik deze gebruik om een API-aanroep uit te voeren, retourneert de service een 403 'Ongeldig token'.
Antwoorden: Als uw app niet bekend was bij het LMS (d.w.z. geen ingeschakelde app-ID), zou u een iets andere foutmelding terugkrijgen. Dit vertelt ons dat hetzij u geen geldige App Sig maakt in uw uiteindelijke API-aanroep (wat waarschijnlijk betekent dat uw app-code niet geschikt is voor uw app-ID), of de User Id-Key die u gebruikt, is op de een of andere manier niet nuttig.
We raden je ten zeerste aan om door de wandeling op de Python-client-SDK-documentatie pagina, zelfs als u niet van plan bent om Python op de lange termijn te gebruiken. Je kunt dit proces interactief en stap voor stap doorlopen, en zo bij elke stap in het proces meer directe controle hebben over wat er aan de hand is om te zien wat er aan de hand is. Met een bedrijfsapp die is gebouwd op basis van C# of Java, moet je je een weg banen door de workflow - die ook prima werken: met een interactieve shell kun je echter elke stap uitvoeren terwijl je bezig bent en de resultaten inspecteren.
Om aan de slag te gaan met de python SDK zoals in die walkthrough, heb je het volgende nodig:
- Om een Python te installeren, en het helpt om het 'pip'-pakket te hebben geïnstalleerd om de python-module te installeren
- Om de 'requests' python module geïnstalleerd te hebben (welke pip automagisch moet vinden)
- Om de 'd2lvalence' python module geïnstalleerd te hebben (welke pip automagisch zou moeten vinden)
Vraag: Ik ging kijken naar de Python auth-pagina waarnaar je verwees, maar ik ben in de war. Die pagina raadt me aan om naar de browser te gaan en de omleidings-URL te vangen nadat ik het resultaat heb teruggekregen van createUrlForAuthentication (met behulp van het php-formaat voor de functie).
Antwoorden:
De manier waarop het model op hoog niveau werkt, is als een driepotig auth-model:
- Je hebt een echte gebruiker met een browser
- U hebt een service of applicatie van derden die de gebruiker (meestal) kan bezoeken en die namens die gebruiker Valence API-aanroepen wil doen
- Je hebt het back-end LMS
Wanneer de echte gebruiker de 3rd party-app bezoekt, moet hij, voordat deze API-aanroepen kan maken, het LMS vragen om een User Id-Key-paar dat bij het App Id-Key-paar past, zodat het namens de gebruiker API-aanroepen kan maken. Om dit te doen, wordt de browser van de gebruiker omgeleid naar het "inlogpad" van het LMS om ervoor te zorgen dat het LMS "weet" wie de gebruiker/browser is:
- Als de browser van de gebruiker al een websessie met LMS heeft, kan het LMS zeggen "Ik weet wie de gebruiker is" en het juiste gebruikers-ID-Key-paar naar de 3rd party-app sturen.
- Als de browser van de gebruiker nog geen sessie heeft, kan het LMS proberen de gebruiker te verifiëren met behulp van de standaardmanier voor dat LMS; DAN kan het het juiste gebruikers-ID-sleutelpaar terugsturen naar de 3rd party-app. (Merk op dat in beide gevallen het gebruikers-ID-Key-paar specifiek wordt gegenereerd voor DIE gebruiker en DIE app: het is niet overdraagbaar naar een ander app-ID-Key-paar.)
Dit driepotige auth-systeem is logisch in het geval dat je echt drie afzonderlijke partijen hebt. In gevallen zoals die van u, waarin u een (headless) IT-service-app wilt schrijven die geen echte "momenteel actieve gebruiker met hun webbrowser" heeft, raden we u meestal aan om een serviceaccount aan te maken - een speciaal doel, "gebruiker" en "rol" die alleen wordt gebruikt voor uw servicetoepassing.
In dit geval moet u een manier hebben om het bovenstaande verificatieproces te doorlopen telkens wanneer u een geldig gebruikers-ID-sleutelpaar nodig heeft voor deze service-"gebruiker". Er zijn een heleboel manieren om dat te doen, maar ze houden allemaal in dat (op een gegeven moment) een echte gebruiker met een echte browser opstaat en de rol van die derde poot in het authenticatieproces speelt.
Wat u meestal doet, is ofwel een lokaal gehoste versie van een van onze eenvoudige voorbeelden gebruiken, ofwel onze online "API Test Tool" (https://apitesttool. desire2learnvalence.com/), of een interactieve Python-sessie met onze Python SDK (zoals in de auth walkthrough waar ik naar verwees). Voor de beste beveiliging raden we u doorgaans aan dit proces binnen een beveiligde omgeving uit te voeren, dus de API-testtool is misschien niet de beste oplossing, vooral als u geen verbinding gaat maken met HTTPS, omdat het op internet staat. Als u echter HTTPS gebruikt om het met uw LMS te verbinden, is het waarschijnlijk voldoende veilig.
Voor het proces van "het verzamelen van een User Id-Key-paar" moet u uw EIGEN App Id-Key-inloggegevens gebruiken (dat wil zeggen, het paar dat u hebt ontvangen voor de app/service die u schrijft).
Als u dit interactief doet, maakt u een app-context met die referenties. Als u een voorbeeld of de online tool gebruikt, geeft u uw eigen App Id-Key-paar op als degene die u wilt gebruiken (niet de standaardsleutels in het formulier: dat zijn enkele set openbare sleutels voor demodoeleinden). U moet de hostnaam van uw LMS opgeven en de poort die u wilt aanroepen. Vervolgens doorloop je het "auth proces":
- Als u een interactieve sessie met de Python SDK gebruikt, maakt u een 'verificatie-URL' die u knipt en in uw browser plakt... om dit te doen, moet u ook een "callback-URL" opgeven die het LMS vertelt waar de gebruikers-ID-sleutel naartoe moet worden gestuurd - we raden localhost aan omdat dat teruggaat naar de computer waar uw browser is, en waarschijnlijk zal uw browser klagen dat hij de URL niet kan vinden, maar u kunt dan de voltooide URL uit de adresbalk kopiëren.
- Als u het voorbeeld of de online tool gebruikt, is de "callback-URL" voor u verborgen - het formulier biedt dit automatisch aan: het gebruikers-ID-sleutelpaar wordt teruggestuurd naar de webserver waarop het voorbeeld/de online tool wordt uitgevoerd.
Bij het teruggeven van het gebruikers-ID-sleutelpaar, zal het LMS ze als queryparameters plaatsen op die "callback-URL" die u hebt opgegeven in het verzoek dat u zojuist hebt verzonden.
- Als u de online tool of een voorbeeld gebruikt, moet de tool/het voorbeeld deze callback-URL automatisch ontbinden, de inloggegevens eruit halen en deze aan u laten zien.
- Als u een interactieve Python-sessie gebruikt, zal het LMS doorverwijzen naar "localhost" en het gebruikers-ID-sleutelpaar in queryparameters overnemen. Kopieer de volledige URL uit de adresbalk van de browser en voer die terug naar uw Python-sessie om de "gebruikerscontext" te creëren - dit zal de gebruikers-ID-sleutels uit die resultaat-URI pellen en een gebruikerscontext voor u creëren die u kunt gebruiken om interactief API-aanroepen te maken ... u kunt het ook inspecteren om te zien wat het gebruikers-ID-sleutelpaar is, ze op schijf opslaan, enzovoort.
In ieder geval bent u er niet in geslaagd "een gebruikers-ID-Key-paar te verzamelen" voor UW serviceaccount om bij UW app-ID-Key te passen. U kunt dat cachen op een veilige plaats die toegankelijk is voor uw beheerdersscript/app (zoals in een configuratiebestand). We raden u ten zeerste aan om het App Id-Key-paar van uw app en alle bijbehorende gebruikers-ID-sleutels te behandelen als zeer gevoelige informatie - met die tokens kan IEDEREEN uw LMS aanroepen en zich voordoen als uw app als een geldige gebruiker, dus u wilt ze op een veilige plaats plaatsen die alleen zichtbaar is voor een klein aantal mensen en voor het script/de app die ze moet gebruiken.
Wanneer het wachtwoord voor dit serviceaccount wordt gewijzigd, moet u dit proces opnieuw doorlopen om een nieuw gebruikers-ID-sleutelpaar te verzamelen. Als uw LMS API-tokens heeft ingesteld om binnen een vaste tijd te verlopen, moet u dit proces ook opnieuw uitvoeren wanneer die tijd is verstreken. LMS'en hebben deze vervaltijd standaard ingesteld op 'onbepaalde tijd' en de User Id-Key-tokens verlopen alleen wanneer het wachtwoord van de gebruiker wordt gewijzigd of de sitebeheerder de toegang tot apps van derden voor die gebruiker weigert.
Voor een ander punt van uitleg kun je dit onderwerp zien op onze ontwikkelaarsblog: Aan de slag met app-id-key-verificatie. Het is enkele jaren oud, maar het materiaal is nog steeds waar, en de diagrammen zijn anders dan die in onze online documenten, zodat contrast kan helpen om een ronder beeld te krijgen.https://d2l.someUniversity.eduhttps://yourServer.org/authCallback
https://apitesttool.desire2learnvalence.com/
https://d2l.someUniversity.eduhttps://yourServer.org/authCallbackhttps://yourServer.org/authCallback