All Cloudlet resources under the path /auth are protected by authentication.
Livebase Cloudlets natively support two authentication methods: one based on JSON Web Token (hereinafter abbreviated as JWT) and one based on HTTP Basic.
JSON Web Token #
JWT is a web standard for data exchange defined by RFC 7519. A JWT token is composed of 3 sections: the header, which contains information about the type of algorithm used for encoding; the payload, which contains the encoded data in JSON format; and a signature that ensures the token’s authenticity.
In addition to the default claims contained in the token’s payload, it is possible to add additional custom claims: for more information on this, please refer to the Authentication settings page.
At a low level, each HTTP request to the API must include the header Authorization: Bearer <MyToken>; the token is obtained by making a POST request to the Cloudlet endpoint:
https://<CloudletURL>/public/token/getJwtToken?format=<format>
Through the format parameter, it is possible to specify the format of the request body: json (default) or xml.
In the request body, the username and password must be specified, alternatively in JSON or XML format, as shown in the example below for the user with username “a1” and password “test”:
{"username":"a1","password":"test"}
<credentials><username>a1</username><password>test</password></credentials>
The token obtained in this way can be used until the expiration specified in the exp attribute of the payload. To check the token’s payload, you can use the debugging tool provided by JWT.
Before a token expires, it can be renewed by obtaining a new token by making a GET request to the Cloudlet endpoint:
https://<CloudletURL>/auth/token/refreshJwtToken
by specifying in the header Authorization: Bearer <MyToken> the token that is about to expire.
For further details on the REST services exposed by the Cloudlet for token management, please refer to the page.
Basic Authentication #
In an HTTP Basic system, user credentials are sent with each request to the server in a specific header and can be stored by the browser. This means that logout is only possible after a period of inactivity or by manually removing the stored credentials from the browser.
At a low level, each HTTP request to the API must include the header Authorization: Basic <MyToken>; the token is the result of Base64 encoding the string <Username>:<Password>. If using cURL, it is therefore necessary to always specify the header as shown above. Higher-level libraries, such as Apollo, must be properly configured by providing the authentication token.