Een API-sleutel

Om een API key te ontvangen van een eLabNext gebruiker voor gebruik binnen uw eigen web-based platform, gebruikt u best de eLabNext 'Authenticatie flow voor 3rd party systemen' optie.

Authenticatiestroom voor webtoepassingen

Hier zijn de vereisten voor het gebruik van dit authenticatiemechanisme:

• Binnen je webgebaseerde platform moet je de gebruiker omleiden naar de URL https://{{eLab Endpoint}/members/fn/externalAuth/?rootVar=MyExampleRootVar&state=myOptionalStateString
• U moet een actieve invoegtoepassing voor de gebruiker hebben ingeschakeld die een statische variabele bevat authReturnURL binnen je naamruimte.
  • Deze variabele moet de volledige URL bevatten naar en eindpunt op je webgebaseerde platform dat een zogenaamde 'verzoektoken‘.

Hieronder zie je een schema hoe de uitwisseling van tokens plaatsvindt. De voorbeeldcode downloaden om het in actie te zien. De voorbeeldcode vereist nodeJS te installeren op je systeem.

De stappen:

1. Gebruiker vraagt API token aan

   Op uw platform zal er een actie zijn voor de eindgebruiker om een API token aan te vragen bij eLabNext. De enige vraag aan de eindgebruiker is naar welk endpoint dit API token aangevraagd moet worden. Dit zorgt ervoor dat organisaties die eLabNext hosten, onder hun eigen domeinnaam, deze functie kunnen gebruiken.

   Dit kan enige uitleg vergen voor eindgebruikers om te begrijpen wat er van hen gevraagd wordt. Idealiter zou je hun invoer valideren/parsen en corrigeren om te eindigen met de juiste syntaxis. (Bijvoorbeeld wanneer een eindgebruiker een pagina kopieert/plakt die hij regelmatig opent, zoals https://www.elabjournal.com/members/wilt u deze invoer misschien accepteren en corrigeren om het echte 'eindpunt' weer te geven, namelijk www.elabjournal.com voordat het wordt omgeleid naar https://{{eLab Endpoint}/members/fn/externalAuth/?rootVar=MyExampleRootVar&state=myOptionalStateString).

   Hier, rootVar moet de rootVar van je add-on zijn. staat is een optioneel parameter die naar je wordt teruggekaatst. Dit kan gebruikt worden om een bepaalde toestandwaarde door te geven en/of om de beveiliging te verhogen door een mechanisme dat aan jouw kant geïmplementeerd is dat replay-aanvallen of parameter-manipulatie voorkomt (bijvoorbeeld door een salted hash van een bekende toestand door te geven).

2. Ontvangt 'Verzoektoken'.

   De gebruiker wordt nu doorgestuurd naar https://{{eLab Endpoint}/members/fn/externalAuth/?rootVar=MyExampleRootVar&state=myOptionalStateString om toestemming te geven. Bij toestemming zal eLabNext de gebruiker naar u terugleiden op basis van de statische variabele authReturnURL in de naamruimte van uw Add-On. Hiermee wordt de retourautor URL aan onze kant voor beveiligingsdoeleinden gewist.

   Merk op dat dit ook werkt tijdens het sideloaden van je script tijdens de ontwikkeling. In dat geval zal de authenticatiestroom standaard in 'Ontwikkelmodus' staan, wat betekent dat het alleen de authReturnURL van uw script dat aan de zijkant is geladen, waarbij lokaal geïnstalleerde add-ons worden omzeild.

3. Wissel 'Request Token' uit met API-token

   De authReturnURL wordt aangeroepen, met het vraagtoken als URL-parameter. Het request token moet binnen 60 seconden worden gebruikt en kan maar één keer worden gebruikt. Aan jouw kant zul je dan de API aanroepen https://{eLab Endpoint}/api/v1/auth/user/exchangeToken
   (hier gedocumenteerd), om het request token te gebruiken voor het ontvangen van een langlevend API token. Zorg ervoor dat u de waarde post als Content-Type application/json.

   De voorbeeldcode downloaden om het in actie te zien. De voorbeeldcode vereist nodeJS te installeren op je systeem.

Verificatiestroom voor desktopapplicaties

De authenticatiestroom lijkt erg op die van webapplicaties.

De vereisten voor het gebruik van dit authenticatiemechanisme zijn:

• Registreer een aangepast en uniek URI-schema voor je bureaubladprogramma, zodat het wordt geopend wanneer het wordt aangeroepen vanuit een browser en de parameters accepteert.
• Idealiter roept u uw eigen desktop programma aan vanuit een Add-On, zodat u de location.host javascript variabele kunt doorgeven, waardoor uw desktop programma weet welk eLab eindpunt te gebruiken. Als je de applicatie volledig stand-alone gebruikt, moet je de gebruiker vragen naar het eLab eindpunt, omdat dit kan verschillen per regio en installatietype.
• Stuur de gebruiker door naar de URL https://{{eLab Endpoint}/members/fn/externalAuth/?rootUri=MyCustomUri&source=descriptionOfMyProgram
• Nadat de gebruiker heeft geaccepteerd, wordt hij doorgestuurd naar: {{Uw aangepaste URI-schema}}:requestToken={{requestToken}}host={{oorspronkelijke host}}

Het verzoektoken dat door je desktopapplicatie wordt ontvangen, moet binnen 60 seconden worden gebruikt en kan maar één keer worden gebruikt. Aan jouw kant zul je dan de API aanroepen https://{eLab eindpunt of host}/api/v1/auth/user/exchangeToken
(hier gedocumenteerd), om het request token te gebruiken voor het ontvangen van een langlevend API token. Zorg ervoor dat u de waarde post als Content-Type application/json.