The Xentara Web Service v1.0
User Manual
Web Service
See also
JSON Web Key, JSON Web Token, OpenID Connect, OpenSSL.

Description

Web Server is type of Xentara microservice. Xentara Web Server using HTTP/1.1 protocol with security extension for sending and receiving requests with security. Furthermore, it has user verification to control the user's activity.

Server Certificate

Xentara Web Service plugin requires SSL self signed certificate to enable secure connection (Https) between the Xentara Web Service and client devices. The SSL self signed certificate used to encrypt the data and authenticate the Xentara Web Service Server on the client devices.

  • The encryption of data ensures the data are readable only by the authorized devices.
  • The authentication by the Xentara Web Service Server ensures the client devices sent the data securely sent to the right web server.

Xentara Web Service requires SSL certificate with the key in PEM format.

Authentication

OpenID Connect

OpenID Connect is an identity layer of the OAuth 2.0 framework. OpenID Connect is an end-user identity protocol which obtains basic profile information using JSON web tokens (JWTs) for authentication.

JSON Web Token

JSON web token is an open standard which offers a compressed self-contained way securely sending JSON-encoded data between parties. JWT tokens can use a public or private pair of keys in the form of a X.509 certificate for signing and can be asymmetrical or symmetrical. The JWT is sent encoded by the sender and is decoded by the recipient device. A decoded JSON Web Token is seperated in three main parts :

  • Header contains information for the algorithm and for the type of the token.
  • Payload contains the claims which are profile information.
  • Signature contains the signature required to verify the JWT.

JWT claims are statements which contain profile information like name or email address. JWT allows customized claims but there are some registered claims that can be found in the table below :

Claim name Claim Description
iss Issuer
sub Subject
aud Audience
exp Expiration time
nbf Not before
iat Issued at time
jti JSON Web Token ID

More registered standard claims can be found in Internet Assigned Numbers Authority.

Verification

Xentara Web Server supports two types of verification for the tokens:

  • Public keys in PEM format
  • JSON Web Key Sets (JWKS)

JWKS verification process can automatically detect the public key from the given key sets. For simple public key verification, the signature verification algorithm and the file containing the public key must be specified.

The Xentara Web Service supports the signature verification algorithms in the table found below :

HMAC RSA ECDSA PSS EdDSA
HS256 RS256 ES256 ES256 ED25519
HS384 RS384 ES256K ES384 ED448
HS512 RS512 ES384 ES512 -
- - ES512 - -

Connection

A client device with valid verification credentials can send and receive HTTP requests with Xentara Web Service . Each request is sent to the Web Service server, first is verified and if the request is verified, the server processes the request.

API Endpoints

Xentara Web Service uses an API of Endpoints to associate the HTTP requests with the datapoints. Endpoints specify locations where the client can read or write specific "value" by sending Http requests. Web Service assigns endpoints by setting a string value name of the endpoint paired with a string value of the primary key of the datapoint.

Data Body

Post

In the body of each HTTP request the Web Service Server expects the "value" in JSON format. It requres one "value" within each request and it can be boolean, string, integer or float. Some examples can be found below :

  • {"value":true}
  • {"value":false}
  • {"value":"Xentara"}
  • {"value":1}
  • {"value":1.23}
Attention
Xentara Influxdb Web Service Server does not contain any attributes