HTTP Server Configuration

Configuring the HTTP server in Xentara involves several crucial steps to ensure secure and efficient operation. This includes setting up Transport Layer Security (TLS) certificates, defining HTTP Server settings, and configuring authentication methods.

Key Steps in Configuration:

TLS Certificates Setup:
- Configure the TLS settings in the security.json file.
- TLS is mandatory for the Xentara WebSocket interface to ensure all connections are encrypted and secure. Detailed instructions for configuring TLS can be found in the TLS Configuration section.
HTTP Server Configuration:
- Define the HTTP server settings within the config.json file. Detailed guidelines are available in the HTTP Server Configuration section.
- If the HTTP server configuration is not specified in the config.json, the server will be disabled by default.
Authentication Methods:
- Set up the authentication methods for the HTTP server in the config.json and related configuration files. For a comprehensive guide, refer to JSON Format for HTTP Authentication Settings in the Xentara user manual.
- Supported authentication methods for WebSocket Connection are mentioned below.
CORS (Cross-Origin resource Sharing) (optional):
- You can restrict access to the WebSocket URL to specific CORS origins.. For a comprehensive guide, refer to JSON Format for CORS (Cross-Origin Resource Sharing) Settings in the Xentara user manual.
Entitlements and Access Control:
- Xentara includes an entitlement called websocket.connect which uses Access Control Lists (ACL) to manage WebSocket connection permissions. This feature allows administrators to specify which clients can establish WebSocket connections.
- Detailed information on implementing ACLs and managing entitlements can be found in the Xentara Security and Authentication section.

Upgrade to WebSocket Connection

The Xentara HTTP server supports upgrading to WebSocket connections when a valid upgrade request is received. This process requires the appropriate authentication credentials.

Upgrade Process:

Authentication Requirements:
- The upgrade request must include an Authorization header with the appropriate credentials based on the selected authentication scheme. ALternatively, authentication can be done via the [token endpoint] described below.
Supported Authentication Schemes:
- "Bearer" Authentication:
  - Uses OAuth 2.0 bearer tokens as described in RFC 6750 — The OAuth 2.0 Authorization Framework: Bearer Token Usage. For details on implementing OAuth 2.0 Authorization, refer to the OAuth 2.0 Authorization section.
- "Basic" Authentication:
  - Utilizes HTTP basic authentication as defined in RFC 7617 — The 'Basic' HTTP Authentication Scheme. This method employs the Xentara Username/Password Authentication.
Handling Missing or Incorrect Authorization:
- If the Authorization header is missing or invalid in the upgrade request, the server responds with a 401 Unauthorized status.
- The response will include a WWW-Authenticate header as specified in RFC 6750 Section 3, guiding the client to provide valid authentication credentials.

WebSocket Connection URI

The WebSocket endpoint provided by the Xentara HTTP server follows a specific URI format to ensure secure communication:

wss://your-xentara-server:port/api/ws

This format uses the wss scheme, indicating a WebSocket connection over TLS, as outlined in the WebSocket Protocol. This ensures that all data transmitted is encrypted and secure.

Authentication Using Short-Lived Access Tokens

In JavaScript, WebSocket connections only support Basic authentication by embedding the username and password in the URL, a feature which is considered deprecated. For this reason, Xentara supports authentication using short-lived access token obtained via a dedicated HTTP endpoint. To obtain a token, youcan send a POST request to the token endpoint. You must include the required HTTP authorization headers as described in the upgrade process above. The body of the POST request should be empty.

Attention: Xentara 2.0 does not support short-lived access tokens. If you receive a “404 Not Found” response when attempting to request a token, then short-lived access tokens are not supported by the version of Xentara running on the target.

The token endpoint as available under the following URL:

https://your-xentara-server:port/api/v1/request-token

The endpoint supports full CORS preflighting, and the a JavaScript script is granted access to any “WWW-Authenticate” header sent in response by means of the CORS “Access-Control-Expose-Headers” header.

If successful, the response from the token enpoint will contain a short-lived token that can be used to establish a WebSocket connecion without using any custom headers. Simply specify the token using a URL query parameter named “token”:

wss://your-xentara-server:port/api/ws?token=6OqVnp0szxsW334tyDvhalDjem_gE-uPOOEHKHHw8ZLnc

Tokens obtained from the token endpoint are valid for 20 seconds.

Note: The Xentara token endpoint only returns URL-safe tokens. Nevertheless, you should use URLSearchParams or encodeURIComponent() to URI-encode the token to guard against potential attackers impersonating the token endpoint.

HTML Welcome Page

It can sometimes be useful to access the WebSocket server using a regular browser. This can be done to check whether the connection works correctly, or to accept self-signed certificates in the browser. For this reason, the Xentara WebSocket server has a welcome page, which can be reached at the root of the server:

https://your-xentara-server:port

Table of Contents