Authentication

In order to obtain authorization, i.e. an access token for the web services, authentication (login) must be performed. Authentication takes place via the REST methods in the /authentication/... ( API {REST} ) section.

When logging in with POST /authentication/user/login ( API {REST} ), a unique access token is created as authorization. The token (access token) created in this way must then be included in the HTTP Header as Authorization header for all other web service requests (e.g. PDF operations).

Logging in to the server can be done as an anonymous login or as a named login (login with user name and password). In the case of anonymous login, no user name and password are transferred at login. In the case of a named login, the user credentials must be passed at login.

caution

In general, it is recommended that calls to the web service authentication are made over an TLS-secured connection, otherwise the token and/or login data will be transmitted in clear text.

Anonymous login

In the default installation of webPDF, the REST API works without user login, i.e. the use of the web service

POST /authentication/user/login ( API {REST} )

is done without specifying any login data, which corresponds to an anonymous login.

caution

Anonymous login may be disabled on the server. In this case, only login with username and password is possible via login.

Example: Anonymous login to the server (without username and password) with curl:

curl -X POST -i -H 'Accept: application/json' http://localhost:8080/webPDF/rest/authentication/user/login  
  
HTTP/1.1 200  
Cache-Control: no-cache, no-store, no-transform, proxy-revalidate, max-age=0  
Content-Type: application/json  
Content-Length: 44

This call results in a response with the JSON structure

{
  "expiresIn": 3599,
  "token": "eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw",
  "refreshToken": ""
}

and the token eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw (access token shortened) for authorization. This token must now be passed for all further calls of the web services (e.g. for the "Documents" web service).

Named login

If the web services or the webPDF server are configured in such a way that anonymous login is not possible, then the user credentials must be transferred during login. The user credentials are checked against the configured user source, which corresponds to a named login. If the check is successful, a corresponding access token is issued.

The login is done via the URI

POST /authentication/user/login ( API {REST} )

The login data are specified via the Authroization header as Basic Authentication (RFC 2617)

Example: Authorization: Basic YWRtaW46YWRtaW4=

curl -X POST -i -H 'Accept: application/json' -H 'Authorization: Basic YWRtaW46YWRtaW4=' http://localhost:8080/webPDF/rest/authentication/user/login

Example: Login to the server with username and password using curl:

curl -X POST -i -H 'Accept: application/json' -H 'Authorization: Basic YWRtaW46YWRtaW4=' http://localhost:8080/webPDF/rest/authentication/user/login  
HTTP/1.1 200  
  
Cache-Control: no-cache, no-store, no-transform, proxy-revalidate, max-age=0  
Content-Type: application/json  
Content-Length: 44  
  
{  
  "expiresIn": 3599,   
  "token": "eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw",  
  "refreshToken": ""  
}

Logout

To invalidate a token and delete the associated document storage or session

POST /authentication/user/logout ( API {REST} )

is called.

The API call must contain the access token of the session to be ended as Authorization header.

curl -X GET -i -H "Accept: application/json" -H 'Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw' http://localhost:8080/webPDF/rest/authentication/user/logout

Request refresh token

To receive a refresh token during login, which is required when the session is extended, this must be explicitly requested. For this purpose, a JSON structure with the field createRefreshToken and the value true must be passed into the call (request body) of the login.

Example: Login with refresh token request

curl -X POST -i -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'Authorization: Basic YWRtaW46YWRtaW4=' -d '{"createRefreshToken": true}' http://localhost:8080/webPDF/rest/authentication/user/login  
  
HTTP/1.1 200  
Cache-Control: no-cache, no-store, no-transform, proxy-revalidate, max-age=0  
Content-Type: application/json  
Content-Length: 1436  
  
{  
"expiresIn": 3599,  
"token": "eyJraWQiOiJmaklQ...92bAOE70J6C5X5Fw",  
"refreshToken": "eyJraWQiOi...rH_AeXnmpTJg"  
}

The response now contains not only the access token token, but also a refresh token under refreshToken, which can be used to extend (renew) the session.