Security

This document provides information on passwords, authentication, SSL configuration, network segregation, encrypted communications, HTTP headers, and the web server TLS protocol as related to the WhatsApp Business API client.

Passwords and Authentication

Please refer to the Login and Authentication documentation for more information about authentication tokens and password best practices.

SSL Configuration

Access to the WhatsApp Business API client requires HTTPS.

The WhatsApp Business API Client generates a self-signed certificate by default when it is created. The Certification Authority (CA) certificate used to generate the self-signed certificate might be required to verify the WhatsApp Business API Client endpoint and avoid a certificate trust warning. Alternatively, you may upload the CA certificate instead of the self-signed certificate. See the CA Certificates documentation for more information.

As Webhooks also requires HTTPS for callbacks; you can use your own CA certificates to prevent the application from running into SSL errors when it attempts to POST to the configured Webhook. See the Webhooks CA Certificate documentation for more information.

Network Segregation

It is recommended you host the Webapp and Coreapp nodes in separate, segregated networks, and expose them only to required services.

The Webapp node should expose the API and the Web Administration endpoints only to networks where WhatsApp Business API clients and management personnel workstations are hosted.

The Coreapp nodes should only expose the communication service to the Webapp nodes, and in a Multiconnect setup, only expose the control service to other Coreapp nodes.

Encrypted Communications

Webapp to Coreapp communication

It is recommended that you set the WA_SECRET environment variable in both the Coreapp and Webapp containers in order to ensure that the communications between them is encrypted.

Note: The Coreapp and Webapp hosts will need to sync their clocks for the encryption to work perfectly. In case of time drifts, the replay protection (i.e., a timestamp check with 10 seconds of grace) might result in communication failure.

Database communication

You can configure SSL parameters used to encrypt the database connection to protect in-transit data.

Previously, only the Coreapp to database connection could be encrypted using the WA_DB_CONNECTION_OPTION environment variable, because traditionally only the Coreapp had access to the database. However, the Webapp container also accesses the database, so it's important to encrypt the Webapp to database connection. For this, the SSL configuration is changed to make it neutral for all containers to access. The encryption can be configured using the following environment variables:

  • WA_DB_SSL_KEY
  • WA_DB_SSL_CERT
  • WA_DB_SSL_CA
  • WA_DB_SSL_VERIFY

WA_DB_SSL_VERIFY can configure whether or not to verify the server identity. This is required in certain internal development setups and it's highly recommended you do not disable verification. If this parameter is not set, verification is turned on by default. To disable verification, use:

WA_DB_SSL_VERIFY=0

Note: WA_DB_SSL_VERIFY is only applicable for the Webapp.

For backward compatibility, WA_DB_CONNECTION_OPTION will continue to be supported in a deprecated mode and used to encrypt the Coreapp to database connection. It's highly recommended you switch to these new parameters.

All the files configured in Key, Cert, and CA environment variables must be accessible inside the container. To do this, you could create a certs directory under the data volume with the appropriate permissions. The data volume is typically mounted as /usr/local/waent/data and the certificate directory would then be accessible at /usr/local/waent/data/certs inside the container.

Web Server (TLS)

The TLS protocol and ciphers have been configured as per Mozilla-recommended configurations. The Webapp supports 3 profiles: MODERN (default), INTERMEDIATE, and OLD.

It is recommended you keep the default configuration for improved security. However, you can choose to downgrade your profile using the WA_WEB_SECURITY_LEVEL environment variable.

HTTP Headers

The following HTTP headers are supported for the Web Admin, but not for API endpoints, and are subject to the browser in use.

NameDescription

X-Content-Security-policy

Defines the policy that only allows scripts from the same domain to run on the Web Admin

X-Frame-Options

Header disallows any domain to include the Web Admin page as an iframe

X-XSS

A protection header that makes the Web Admin page safe from cross-site scripting attacks by sanitizing the inputs if an attack is detected

X-Content-Type-Options

Ensures that content type received by the server are the same as requested by the server

Strict-Transport-Security

Ensures that the Web Admin can only be accessed over HTTPS