Der Erhalt einer API-Schlüssel

Um einen API-Schlüssel von einem eLabNext-Benutzer zur Verwendung innerhalb Ihrer eigenen webbasierten Plattform zu erhalten, verwenden Sie am besten die eLabNext-Option "Authentifizierungsfluss für Systeme von Drittanbietern".

Authentifizierungsablauf für Webanwendungen

Hier sind die Voraussetzungen für die Verwendung dieses Authentifizierungsmechanismus:

• Innerhalb Ihrer webbasierten Plattform müssen Sie den Benutzer auf die folgende URL umleiten https://{{eLab Endpoint}/members/fn/externalAuth/?rootVar=MyExampleRootVar&state=myOptionalStateString
• Sie müssen ein aktives Add-On für den Benutzer aktiviert haben, das eine statische Variable enthält authReturnURL innerhalb Ihres Namensraumes.
  • Diese Variable muss die vollständige URL und den Endpunkt auf Ihrer webbasierten Plattform enthalten, die in der Lage ist, eine so genannte 'Anfrage-Token‘.

Unten sehen Sie ein Diagramm, das zeigt, wie der Austausch von Token abläuft. Laden Sie den Beispielcode herunter um es in Aktion zu sehen. Der Beispielcode erfordert nodeJS die auf Ihrem System installiert werden sollen.

Die Schritte:

1. Benutzer initiiert Anfrage für API-Token

   Auf Ihrer Plattform gibt es eine Aktion, mit der der Endnutzer ein API-Token von eLabNext anfordern kann. Der Endbenutzer wird lediglich gefragt, an welchem Endpunkt dieses API-Token angefordert werden muss. Dadurch wird sichergestellt, dass Organisationen, die eLabNext unter ihrem eigenen Domainnamen hosten, diese Funktion nutzen können.

   Dies kann für die Endnutzer erklärungsbedürftig sein, damit sie verstehen, was von ihnen verlangt wird. Im Idealfall würden Sie ihre Eingaben validieren/parsen und korrigieren, um die richtige Syntax zu erhalten. (z. B. wenn ein Endnutzer eine Seite, auf die er regelmäßig zugreift, kopieren/einfügen würde, wie z. B. https://www.elabjournal.com/members/können Sie diese Eingabe akzeptieren und korrigieren, um den wahren "Endpunkt" wiederzugeben, der lautet www.elabjournal.com vor der Umleitung an https://{{eLab Endpoint}/members/fn/externalAuth/?rootVar=MyExampleRootVar&state=myOptionalStateString).

   Hier, rootVar muss der RootVar Ihres Add-Ons sein. Staat ist eine optional Parameter, der an Sie zurückgesendet wird. Dies kann verwendet werden, um einen Zustandswert zu übergeben und/oder um die Sicherheit durch einen auf Ihrer Seite implementierten Mechanismus zu erhöhen, der Replay-Attacken oder Parametermanipulationen verhindert (z. B. durch Übergabe eines gesalzenen Hashs aus einem bekannten Zustand).

2. Erhält 'Request Token'

   Der Benutzer wird nun von Ihnen weitergeleitet zu https://{{eLab Endpoint}/members/fn/externalAuth/?rootVar=MyExampleRootVar&state=myOptionalStateString um die Zustimmung zu erteilen. Wenn die Zustimmung vorliegt, leitet eLabNext den Benutzer anhand der statischen Variable authReturnURL innerhalb Ihres Add-On-Namensraumes. Dadurch wird die Rückgabe-URL auf unserer Seite aus Sicherheitsgründen auf eine Whitelist gesetzt.

   Bitte beachten Sie, dass dies auch funktioniert, wenn Sie Ihr Skript während der Entwicklung sideloaden. In diesem Fall wechselt der Authentifizierungsfluss standardmäßig in den "Entwicklungsmodus", d. h. er liest nur die authReturnURL von Ihrem seitengeladenen Skript aus, wobei alle lokal installierten Add-ons umgangen werden.

3. Anfrage-Token" mit API-Token austauschen

   Die authReturnURL aufgerufen, die das Anfrage-Token als URL-Parameter enthält. Das Anfrage-Token muss innerhalb von 60 Sekunden verwendet werden und kann nur einmal verwendet werden. Auf Ihrer Seite werden Sie dann den API-Aufruf https://{eLab-Endpunkt}/api/v1/auth/user/exchangeToken
   (hier dokumentiert), um das Anfrage-Token für den Empfang eines langlebigen API-Tokens zu verwenden. Stellen Sie sicher, dass Sie den Wert als Content-Type application/json posten.

   Laden Sie den Beispielcode herunter um es in Aktion zu sehen. Der Beispielcode erfordert nodeJS die auf Ihrem System installiert werden sollen.

Authentifizierungsablauf für Desktop-Anwendungen

Der Authentifizierungsablauf ist dem von Webanwendungen sehr ähnlich.

Die Voraussetzungen für die Verwendung dieses Authentifizierungsmechanismus sind:

• Registrieren Sie ein benutzerdefiniertes und eindeutiges URI-Schema für Ihr Desktop-Programm, damit es sich öffnet, wenn es von einem Browser aufgerufen wird, und seine Parameter akzeptiert.
• Idealerweise rufen Sie Ihr eigenes Desktop-Programm aus einem Add-On heraus auf, so dass Sie die location.host-Javascript-Variable übergeben können, die es Ihrem Desktop-Programm ermöglicht, den zu verwendenden eLab-Endpunkt zu ermitteln. Wenn Sie die Anwendung vollständig eigenständig verwenden, müssen Sie den Benutzer nach dem eLab-Endpunkt fragen, da dieser je nach Region und Installationsart unterschiedlich sein kann
• Umleitung des Benutzers auf die URL https://{{eLab Endpoint}/members/fn/externalAuth/?rootUri=MyCustomUri&source=descriptionOfMyProgram
• Nachdem der Benutzer akzeptiert hat, erfolgt eine Umleitung zu: {{Ihr benutzerdefiniertes URI-Schema}}:requestToken={{requestToken}}host={{ursprungshost}}

Das von Ihrer Desktop-Anwendung erhaltene Anfrage-Token muss innerhalb von 60 Sekunden verwendet werden und kann nur einmal verwendet werden. Auf Ihrer Seite werden Sie dann den API-Aufruf https://{eLab Endpunkt oder Host}/api/v1/auth/user/exchangeToken
(hier dokumentiert), um das Anfrage-Token für den Empfang eines langlebigen API-Tokens zu verwenden. Stellen Sie sicher, dass Sie den Wert als Content-Type application/json posten.