 |
The Xentara Web Service v1.3
User Manual
|
|
The Xentara Web Service v1.3
User Manual
|
A JSON object describing a Web Service Server has the following syntax:
| id | A string value containing the ID of the server. The ID is used to construct the server’s primary key. |
| uuid | A string value containing the unique UUID of the server. |
| portNumber | A numeric value containing the TCP port number the server should listen on. |
| authentication | A JSON object describing the authentication scheme used by the server. The format of this object is described below. |
| serverCertificate | An string value containing the absolute path to the server certificate. The certificate file must be a PEM format file, and must include both the actual certificate, and the accociuated private key. See here for an example of the structure of a valid server certificate file. |
| endpoints | A JSON object containing the list of endpoints. Each member of the object defines a single endpoint. The name of the member (before the colon) defines the path of the endpoint. The path must be a valid URL path element, and must start with a slash (“/”). The path must not end in a slash (“/”). The value of the member (after the colon) defines the data point associated with the endpoint. It must be a string value containing the primary key of a Xentara data point or Xentara I/O point. |
The authentication is represented by a double nested JSON object. The outer object has a single member whose name is the authentication method, and whose value is another JSON object that contains the actual authentication parameters.
The Xentara Web Service always uses JSON Web Tokens for authentication. The Authentication method string must always be @JWT.
The JSON object describing the authentication scheme has the following syntax:
| realm | An optional string value containing the realm to be returned in the WWW-Authenticate header in authentication error responses. The realm is a purely informative value intended to be used by the client to select the correct authentication provider. It is in essence an arbitrary value, but should be different for servers that use a different authentication scheme. The “realm” directive is described in section 1.2. of RFC 2617 — Basic and Digest Access Authentication. |
| scope | An optional array of string values containing the scope values to be returned in the WWW-Authenticate header in authentication error responses. The scope attribute is tell the client which scope it needs to request from an OAuth 2.0 authorization provider. The “scope” attribute is described in section 3.3. of RFC 6749 — The OAuth 2.0 Authorization Framework. If you are using an OpenID Connect authorization provider, don’t forget to include the string “openid” in the scope, as described in 5.4. Requesting Claims using Scope Values in the OpenID Connect Core 1.0 specification. In OpenID Connect, the scope is used to tell the authorization provider which claims it should include in the token.
|
| issuer | A string value specifying the allowed issuer of the token. This is in general the URL of the authentication provider. The issuer specified here is checked against the iss claim of the authentication token. |
| audience | A string value specifying the required audience of the token. The audience specifies the purpose for which a token was issued. The audience specified here is checked against the aud claim of the authentication token. |
| claims | An optional JSON object specifying any additional claims to be checked. Each member specifies a claim name, together with an array of allowed values. The values are checked as described in Additional JWT Claims. |
| verification | A JSON object specifying the method used to verify the signature of the token. The format of this object is described below. |
The verification is represented by a double nested JSON object. The outer object has a single member whose name is the verification method, and whose value is another JSON object that contains the actual verification parameters.
Public key verifies the signature using the known public key of the issuer. The JSON object describing public key verification has the following syntax:
The verification method descriptor in the outer JSON object specifies the algorithm the issuer uses to sign the authentication token. The following algorithms are supported:
| keyFile | An string value containing the absolute path to the file containing the issuer’s public key. The file must be in PEM format. |
Public key verifies the signature using a JSON Web Key Set.
| keyFile | An string value containing the absolute path to a locally stored copy of the issuer’s JWK Set file. JWKS files are in JSON format. |