WebSocket Connection

See also

RFC 6455 - The WebSocket Protocol

RFC 8446 - The Transport Layer Security (TLS) Protocol Version 1.3

2.1. Authorization Request Header Field

RFC 7519 — JSON Web Token (JWT)

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:

1. 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.
2. 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.
3. 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 the Authentication Methods section.
   • Supported authentication methods for WebSocket Connection are mentioned below.
4. 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:

1. Authentication Requirements:
   • The upgrade request must include an Authorization header with the appropriate credentials based on the selected authentication scheme.
2. 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.
3. 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.