Webservice Authentication

Bei den RESTful-Webservices benutzt der webPDF-Server einen "Dokumentenspeicher" (Storage) auf dem Server, um die zu bearbeitende Dokumente zwischen den einzelnen Webservice-Aufrufen zu speichern.

 

Um diesen Storage zu erstellen muss über den URI

 

/webPDF/rest/authentication/...

 

eine Anmeldung (Authentifizierung) am webPDF-Server erfolgen. Bei dieser Anmeldung wird dann eindeutiger Token erstellt und dem Storage zugeordnet. Der so erstellte Token (ID des Storage) muss dann bei allen anderen Webservice-Anfragen (z.B. PDF-Funktionen) mitgegeben werden. Über den Token wird dann der Storage selektiert und innerhalb des Storage über die "Dokumenten-ID" das jeweilige Dokument.

 

Beispiel:

 

Anmeldung am Server (ohne Benutzer-Login) mit

 

/webPDF/rest/authentication/user/login

 

führt zu einer Antwort mit der JSON-Struktur

 

{
"token":"1797964B10A84AE2937FAA712C2CAE2B"
}

 

und dem Token für den Storage des Benutzers. Dieser Token muss jetzt bei allen weiteren Aufrufen der Webservices (z.B. beim Webservice "Documents") übergeben werden.

 

hint

Grundsätzlich wird empfohlen, das die Aufrufe des Webservice Authentication über eine SSL-gesicherte Verbindung ausgeführt werden, da sonst der Token und/oder die Login-Daten im Klartext übertragen werden.

 

Übergabe des Token

 

Die Übergabe des Token kann auf zwei Arten erfolgen:

 

1) als Field "Token" im HTTP-Header des Requests (RFC 2616 - 14 Header Field Definitions) oder

2) als Query-Parameter "Token" in der URL

 

Beispiel mit Parametern in der URL:

 

/webPDF/rest/authentication/user/info?Token=AAC5A982797B3ABC8E97CC3C123A2F5B

 

Anmeldung mit Login

 

In der Standard-Installation von webPDF arbeiten die RESTful-Webservices ohne Benutzer-Anmeldung, d.h. die Nutzung des Webservice "authentication" erfolgt ohne Angabe von Login-Daten (wie zuvor im Beispiel dargestellt).

 

Sind die Webservices bzw. der webPDF-Server allerdings durch eine Benutzeranmeldung gesichert, so müssen bei der Anmeldung Login-Daten ("user credentials") übergeben werden. Die Angabe der Login-Daten kann dabei auf zwei Wegen erfolgen:

 

1) Basic Authentication (RFC 2617) im HTTP Authorization Header oder

2) als Query-Parameter "username" und "password" in der URL

 

hint

Bei der Übergabe im "Authroization Header" müssen Benutzer und Password als "Base64 encoded" übergeben werden (Authorization: Basic YWRtaW46YWRtaW4=).

 

Beispiel mit Parametern in der URL:

 

/webPDF/rest/authentication/user/login?username=admin&password=admin

 

Abmeldung mit Logout

 

Um einen Token ungültig zu machen und den zugeordneten Storage zu löschen, wird z.B.

 

/webPDF/rest/authentication/user/logout?Token=AAC5A982797B3ABC8E97CC3C123A2F5B

 

aufgerufen.