Configuring WebSocket over HTTPS

Problem

Hypertext Transfer Protocol (HTTP) transmits information in plain text. In comparison, Hypertext Transfer Protocol Secure (HTTPS) is a network communication protocol built on Secure Sockets Layer (SSL) and HTTP, enabling encrypted data transmission and identity authentication, which makes it more secure than HTTP.

Two methods are available for configuring WebSocket in an HTTPS environment, as detailed in the following sections.

Note: 

Starting from the FineReport project of V11.0.2 and later versions, a container-based WebSocket solution has been added. You are advised to first check if the container-based WebSocket solution can be used.

No user operation, manual configuration, or additional port opening is required. The system automatically uses the WebSocket built into the web container for connection, and the WebSocket connection reuses the HTTP port.

Solution

Method one: If NGINX is not used, SSL can be configured directly on the web server.

Method two: If NGINX is used as a reverse proxy server, SSL should be configured on NGINX, while the application server (for example, Tomcat) does not require SSL configuration. In this way, communication between the client and NGINX is handled over HTTPS, and communication between NGINX and Tomcat is handled over HTTP through the proxy_pass directive.

Note: 

1. You can configure WebSocket via a visual interface on the decision-making platform. For details, see the "WebSocket Setting" section in General.

2. If WebSocket Setting shown in the following figure is not displayed on the decision-making platform, the WebSocket connection is already properly configured, requiring no further modification.

3. When HTTPS access is configured, and WebSocket settings are configured under System Management > System Setting > General:

You must first restore the WebSocket settings to the default under System Management > System Setting > General before replacing the certificate, and then reconfigure the WebSocket settings.

If the certificate is replaced first without restoring the WebSocket settings, you may be unable to access the platform.

This section demonstrates how to configure WebSocket using method one in a Windows system.

HTTPS Environment Setup

For details about how to set up the HTTPS environment, see HTTPS Access by Configuring the SSL Certificate in Tomcat.

Database Configuration

Add four parameters to the fine_conf_entity table in the FineDB database, as listed in the following table.

For details, see FineDB Database Introduction.

The following figure shows the parameter values to be added for the WebSocketConfig.keyStore and WebSocketConfig.keyStorePassword fields.

Note: 

The value for WebSocketConfig.keyStore in the fine_conf_entity table must be an absolute path rather than a relative path.

The following figure shows the parameter information added to the database table.

After the configuration, restart the report server for the modification to take effect.

Note: 

After you configure WebSocket over HTTPS, WebSocket requests over HTTP will no longer work.

This section demonstrates how to configure WebSocket using method two in an environment consisting of Linux, NGINX, and Tomcat.

Note: 

1. Avoid using self-signed certificates unless necessary, as they may result in data loss. For details, see the "Certain Browser Settings Not Taking Effect" section.

Self-Signed SSL Certificate Generation

Note: 

You can skip this section if you already have a certificate.

1. Install OpenSSL and verify if the installation was successful.

# yum install openssl openssl-devel
# openssl version -a

2. Generate the key file server.key.

# openssl genrsa -des3 -out server.key 2048

You are required to set a password for the key file. Ensure that you remember the password.

In this way, the key file server.key is generated. The password is required each time you use the file, for example, when NGINX loads server.key during startup.

If you find this troublesome, you can remove the password from server.key with the following command:

# openssl rsa -in server.key -out server.key

3. Generate the certificate signing request (CSR) file server.csr.

# openssl req -new -key server.key -out server.csr

For Country Name, enter a two-letter country code (for example, US). For Common Name, enter the server's hostname. If either of the fields is left blank, the browser will display a security warning. The other fields can be left blank.

4. Generate the Certificate Authority (CA) certificate file ca.crt.

# openssl req -new -x509 -key server.key -out ca.crt -days 3650

The CA certificate is used to sign your own certificate.

5. Generate the server certificate file server.crt.

# openssl x509 -req -days 3650 -in server.csr -CA ca.crt -CAkey server.key -CAcreateserial -out server.crt

6. Check the five generated files, among which server.crt and server.key are the certificate files required by NGINX.

HTTPS Configuration for NGINX

The default port for HTTP is 80, and the default port for HTTPS is 443.

You can click to download the full NGINX configuration file: nginx-demo.conf.zip

Note: 

After modifying nginx.conf, do not restart NGINX using the reload command. Instead, run stop followed by start; otherwise, the configuration changes may not take effect.

1. Configure port 443.

server {
        listen       443 ssl;
        server_name  192.168.5.232;
     
        ssl_certificate      /mnt/hgfs/share/keys/server.crt; #Absolute path of the certificate file
        ssl_certificate_key  /mnt/hgfs/share/keys/server.key; #Absolute path of the key file
        ssl_session_cache    shared:SSL:1m; #SSL session cache type and size  
        ssl_session_timeout  5m; #Session timeout
 
        ssl_ciphers  ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP; #Allowed cipher suites by the server for a secure connection
        ssl_prefer_server_ciphers  on; #Server ciphers using SSLv3 and TLSv1 take precedence over client ciphers.
     
        #You must hide server version in response headers to prevent version-based attacks.
        #server_tokens off;
        #If the entire site uses HTTPS and HTTP is not required, you can enable HSTS to inform browsers to enforce HTTPS access.
        #fastcgi_param   HTTPS               on;
        #fastcgi_param   HTTP_SCHEME         https;
     
        location / {
            proxy_http_version 1.1;
            proxy_set_header Connection "";
 
            proxy_buffering off;
            proxy_next_upstream http_500 http_502 http_503 error timeout invalid_header non_idempotent;
 
            proxy_redirect off;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            # Inform the backend container (for example, Tomcat) that the original request was HTTPS; otherwise, the container may treat it as an HTTP request.
            proxy_set_header X-Forwarded-Proto $scheme;
             
            proxy_connect_timeout    20;
            proxy_read_timeout       1000;
            proxy_send_timeout       300;
 
            proxy_pass http://FR.com;
        }

2. Configure the WebSocket port.

Configuring WebSocket to use HTTPS can be error-prone. After starting the cluster, check if the chart for real-time memory usage is displayed under Intelligent O&M > Load Management > Load Surveillance to confirm that the WebSocket connection is working properly.

server { 
      listen       38889 ssl;            
      server_name  192.168.5.232;
 
      ssl_certificate      /mnt/hgfs/share/keys/server.crt;
      ssl_certificate_key  /mnt/hgfs/share/keys/server.key;
 
      ssl_session_cache    shared:SSL:1m;
      ssl_session_timeout  5m;
 
      ssl_ciphers  ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
      ssl_prefer_server_ciphers  on;
      location / {
          proxy_request_buffering off;
          proxy_buffering off;
          proxy_connect_timeout 20;
          proxy_read_timeout 1000;
          proxy_send_timeout       300;
          proxy_http_version 1.1;
          proxy_set_header Upgrade $http_upgrade;
          proxy_set_header Connection "upgrade";
          proxy_pass http://WBS.com;
       }
  }

By default, NGINX listens on port 38889 for forwarding, and the node's WebSocket service listens on port 38888. You can modify the ports as needed. Port forwarding is configured using the parameter WebSocketConfig.requestPorts in the fine_conf_entity table. Multiple ports can be configured forward to the same WebSocket service, as shown in the following table.

Port forwarding can also be configured directly on the decision-making platform. For details, see the "WebSocket Setting" section in General.

Note: 

For JAR packages dated 2019-09-27 or earlier, the parameter for configuring port forwarding is WebSocketConfig.requestPort, which supports only one port, as shown in the following table.

3. Redirect HTTP to HTTPS.

rewrite ^(.*)$  https://$server_name$1 permanent;

4. Configure Cross-Origin Resource Sharing (CORS) in NGINX.

add_header access-control-allow-Headers X-Requested-With;
add_header access-control-allow-Methods GET,POST,OPTIONS;

Note: 

Do not add the directive add_header Access-Control-Allow-Origin * in NGINX, which may already be configured on the frontend. Adding this directive in NGINX may override or conflict with the frontend configuration, resulting in cross-origin request errors.

Certain Browser Settings Not Taking Effect

Problem

After you configure WebSocket with method two, Firefox still displays a blank page, while Internet Explorer (IE) fails to record template access activities.

This happens because the self-signed certificate is not trusted by the browser. The page is accessible only due to a manually added exception, but port 38888 is not added, causing the browser to intercept the WebSocket request.

Solution

You can press F12 to check the intercepted request, copy it, and access port 38888 directly to add a security exception, or add it manually.

In this way, you can view the real-time memory usage on the platform, as shown in the following figure.

Others

1. Key path limitations:

• Both absolute and relative paths can be used in the Tomcat configuration file server.xml.

• The value of SSL Key Path under System Management > System Setting > General > HTTPS Setting on the decision-making platform can only be an absolute path.

2. You cannot configure HTTPS for the designer and FineBI installed through the EXE file.

3. If HTTPS is configured in NGINX, do not configure it again under System Management > System Setting > General > HTTPS Setting.

2. You can access HTTPS-enabled projects deployed in Tomcat through both HTTP and HTTPS. However, WebSocket only allows you to access projects either through HTTPS or HTTP. That is, while the HTTPS connection can work, the HTTP connection will fail.

Projects configured with NGINX will remain affected: you can access them through both HTTP and HTTPS.