Frage:
Wie können 401-Fehler in Bezug auf nicht freie Lizenzen bei der Verwendung der DocuWare API vermieden werden?
Antwort:
Im Allgemeinen gibt es zwei Möglichkeiten. Entweder die Verwendung von Cookies, um die Sitzung am Leben zu erhalten, oder die Verwendung von Token, um die alte Sitzung wieder zu verwenden. Das Verfahren dazu ist im Folgenden beschrieben.
Im Allgemeinen gibt es zwei Möglichkeiten. Entweder die Verwendung von Cookies, um die Sitzung am Leben zu erhalten, oder die Verwendung von Token, um die alte Sitzung wieder zu verwenden. Das Verfahren dazu ist im Folgenden beschrieben.
Authentifizierung:
Bevor das Cookie/Token verwendet werden kann, ist eine erste Sitzung erforderlich. Dazu muss sich die Anwendung bei DocuWare anmelden. Dazu senden Sie einen Post-Request mit den Authentifizierungsdaten an den Endpunkt /Account/Logon. Die Antwort enthält mindestens die folgenden beiden Cookies: .DWPLATFORMAUTH und DWPLATFORMBROWSERID.
LogOff:
Bei einer Abmeldung über den Endpunkt /Account/LogOff wird der Benutzer von DocuWare abgemeldet. Das aktuelle Session-Cookie wird ungültig und kann danach nicht mehr verwendet werden. Das bedeutet, dass eine neue Sitzung angelegt werden muss. Erfolgt innerhalb von zwei Minuten ein weiterer Anmeldeversuch und ist keine freie Lizenz verfügbar, wird der HTTP-Statuscode 401 mit der Meldung "Keine der registrierten Lizenzen ist für den Client [Benutzername] verfügbar" zurückgegeben.
Vermeiden Sie die 401-Antwort:
Um den oben beschriebenen 401-Statuscode zu vermeiden, kann eine der folgenden Optionen verwendet werden.
Halten Sie die Sitzung mit Hilfe von Cookies am Leben:
Speichern Sie nach der Anmeldung das Cookie .DWPLATFORMAUTH in einem Cookie-Container. Das Cookie aus dem Cookie-Container kann nun bei jeder folgenden Anfrage an die DocuWare API verwendet werden. Solange keine Abmeldung erfolgt, kann die Anwendung die alte Sitzung ohne erneute Authentifizierung nutzen und verbraucht nur eine Client-Lizenz. Verwenden Sie diese Methode, wenn die Anwendung in unregelmäßigen Abständen Anfragen an die DocuWare-API sendet. Die Lebensdauer des Cookies ist auf 20 Jahre eingestellt und sollte funktionieren, solange keine Abmeldung erfolgt.
Reconnect innerhalb von zwei Minuten mit einem Token:
Manchmal ist ein Reconnect zur DocuWare-API innerhalb von zwei Minuten nach Aufruf des /Account/LogOff-Endpunkts notwendig. Um den 401-Fehler zu vermeiden, kann ein Token verwendet werden, anstatt die Sitzung mit Hilfe des Cookies aufrechtzuerhalten. Das Token kann vor der Abmeldung erstellt werden, indem der Endpunkt /Organizations/LoginToken per Post-Methode aufgerufen wird. Dieser Aufruf erfordert einen Body, in dem das Zielprodukt, die Verwendung (Multi, Single) und die Lebensdauer angegeben werden. Bitte sehen Sie sich den folgenden Beispiel-JSON-Body zur Erstellung eines Tokens an:
{
"TargetProducts":["PlatformService"],
"Usage": "Multi" ,
"Lifetime":"1.00:00:00"
}
Die Antwort enthält das Token, das von der Plattform bereitgestellt wird. Anschließend kann die Authentifizierung durchgeführt werden, indem das Token per Post an /Account/TokenLogOn gesendet wird. Diese Authentifizierungsmethode ermöglicht die Wiederverwendung der Benutzerlizenz, die vor dem Abmeldevorgang in Gebrauch war. Das Token hat eine Lebenszeit, die bei der Anforderung des Tokens eingestellt werden kann (Parameter Lifetime). Die meisten DocuWare-Anwendungen (z.B. Desktop Apps) verwenden ein Token mit einer Lebensdauer von 365 Tagen. Um diesen Vorgang zu wiederholen, ist es wichtig, vor der Abmeldung ein neues Token zu erstellen und immer das neueste Token für die Anmeldung zu verwenden.
LogOff:
Bei einer Abmeldung über den Endpunkt /Account/LogOff wird der Benutzer von DocuWare abgemeldet. Das aktuelle Session-Cookie wird ungültig und kann danach nicht mehr verwendet werden. Das bedeutet, dass eine neue Sitzung angelegt werden muss. Erfolgt innerhalb von zwei Minuten ein weiterer Anmeldeversuch und ist keine freie Lizenz verfügbar, wird der HTTP-Statuscode 401 mit der Meldung "Keine der registrierten Lizenzen ist für den Client [Benutzername] verfügbar" zurückgegeben.
Vermeiden Sie die 401-Antwort:
Um den oben beschriebenen 401-Statuscode zu vermeiden, kann eine der folgenden Optionen verwendet werden.
Halten Sie die Sitzung mit Hilfe von Cookies am Leben:
Speichern Sie nach der Anmeldung das Cookie .DWPLATFORMAUTH in einem Cookie-Container. Das Cookie aus dem Cookie-Container kann nun bei jeder folgenden Anfrage an die DocuWare API verwendet werden. Solange keine Abmeldung erfolgt, kann die Anwendung die alte Sitzung ohne erneute Authentifizierung nutzen und verbraucht nur eine Client-Lizenz. Verwenden Sie diese Methode, wenn die Anwendung in unregelmäßigen Abständen Anfragen an die DocuWare-API sendet. Die Lebensdauer des Cookies ist auf 20 Jahre eingestellt und sollte funktionieren, solange keine Abmeldung erfolgt.
Reconnect innerhalb von zwei Minuten mit einem Token:
Manchmal ist ein Reconnect zur DocuWare-API innerhalb von zwei Minuten nach Aufruf des /Account/LogOff-Endpunkts notwendig. Um den 401-Fehler zu vermeiden, kann ein Token verwendet werden, anstatt die Sitzung mit Hilfe des Cookies aufrechtzuerhalten. Das Token kann vor der Abmeldung erstellt werden, indem der Endpunkt /Organizations/LoginToken per Post-Methode aufgerufen wird. Dieser Aufruf erfordert einen Body, in dem das Zielprodukt, die Verwendung (Multi, Single) und die Lebensdauer angegeben werden. Bitte sehen Sie sich den folgenden Beispiel-JSON-Body zur Erstellung eines Tokens an:
{
"TargetProducts":["PlatformService"],
"Usage": "Multi" ,
"Lifetime":"1.00:00:00"
}
Die Antwort enthält das Token, das von der Plattform bereitgestellt wird. Anschließend kann die Authentifizierung durchgeführt werden, indem das Token per Post an /Account/TokenLogOn gesendet wird. Diese Authentifizierungsmethode ermöglicht die Wiederverwendung der Benutzerlizenz, die vor dem Abmeldevorgang in Gebrauch war. Das Token hat eine Lebenszeit, die bei der Anforderung des Tokens eingestellt werden kann (Parameter Lifetime). Die meisten DocuWare-Anwendungen (z.B. Desktop Apps) verwenden ein Token mit einer Lebensdauer von 365 Tagen. Um diesen Vorgang zu wiederholen, ist es wichtig, vor der Abmeldung ein neues Token zu erstellen und immer das neueste Token für die Anmeldung zu verwenden.
KBA ist sowohl für Cloud- als auch für On-Premise-Organisationen anwendbar.
Bitte beachten Sie: Dieser Artikel ist eine Übersetzung aus dem Englischen. Die in diesem Artikel enthaltenen Informationen basieren auf der/den englischsprachigen Originalversion(en) des Produkts. In der übersetzten Version unserer Artikel können kleinere Fehler enthalten sein, z.B. in der Grammatik. Wir können zwar nicht für die vollständige Richtigkeit der Übersetzung garantieren, aber in den meisten Fällen werden Sie sie als ausreichend informativ empfinden. Im Zweifelsfall wechseln Sie bitte zurück zur englischen Version dieses Artikels.
