Objective

Authenticating or verifying delivered callback (webhook) events.

Applies To

• Webhook
• Callback
• Video API

Procedure

The Vonage Video API (OpenTok) Platform offers various ways to authenticate the callback (Webhook) events delivered from our servers. Customers can choose to use one or many of the following ways to verify the delivered callback events.

Enabling Secured callback (Recommended)

You can enable secure callback directly on your project dashboard. The secure callbacks feature provides a method for your application to verify a webhook callback request is coming from Vonage and its payload has not been tampered with during transit. When receiving a request, the incoming callback webhook will include a JWT token in the authorization header, which is signed with your signature secret. More details here

Enabling HTTPS instead of HTTP

Customers may choose to receive the events delivered over plain HTTP. However, for better security and authenticity, we recommend to use HTTPS where possible. However, you can choose to combine HTTP with IP Whitelisting.

Enabling TLS Mutual Authentication for HTTPS connections

Note: Once the secured callbacks feature is enabled, TLS Mutual Authentication for HTTPs connection is no longer applicable and should not be used. (Please let us know if this is a method that you expect to use together with a signed callback implementation.)

OpenTok Platform supports TLS mutual authentication for additional security where customers’ servers can authenticate and verify the identity of the various TokBox servers invoking the Webhooks.

During the SSL Handshake, the customer’s HTTPS server must request for a Client Certificate via sending the Certificate Request message. Since Certificate Request is an optional SSL handshake message, you’d need to make necessary configuration changes to enable it.

OpenTok Client Certificate

The customer's HTTPS server may choose to verify the fingerprint of the received certificate. Please reach out to the Support Team to get the latest fingerprints for OpenTok certificate.

Configuring the TLS Mutual Authentication for Nginx

(Similar instructions should apply for another HTTP Servers.)

The following configuration in nginx.conf will enable TLS Mutual authentication. The parameter ssl_verify_client should be set to on. See the Nginx wiki for additional configuration parameters.

ssl_client_certificate /home/tokbox/client_ca_root.pem;
ssl_verify_client on;
ssl_verify_depth 10;

Configuring the CA Certificate Chain

You need to create a PEM file with DigiCert's (OpenTok's certificate CA) CA certificate and point ssl_client_certificate to it. For additional intermediate CA certificates that are not sent by the Client, you should prepend them to the PEM file. The ssl_verify_depth can usually be set to the number of intermediate CA certificates the client certificate chain has or simply how deep the certificate chain is from end (or server) certificate to the trusted Root CA certificate. It is usually safer to keep a maximum to 10.

CA Certificates

Currently, the OpenTok Client certificate chain has following Intermediate and Root CA certificates: 

• Root CA Certificate: digitcert-root.crt

• Intermediate CA Certificate: digicert-intermediate.crt

These are DER (Binary formatted) certificates. You can convert these to PEM (Base-64) format and append each other in a single file (first being intermediate followed by CA).

Implementing Secure Client Verification

Nginx (or similar) servers will verify whether the received certificate can be trusted. As part of that, the Customer’s HTTPS server should validate the Client's hostname or domain name. The domain name received as part of the certificate can be verified by comparing against the pre-configured domain name.

If Nginx is used as a proxy server, often terminating the SSL connections, you could set custom proxy headers with necessary attributes from the client certificate which will eventually be validated by the application logic.

In that case, with the following configuration, Nginx will populate the $ssl_client_s_dn variable with the Subject DN (Distinguished Name) present in the client certificate. This value can be parsed and manually compared by the application logic to verify that the domain matches. Refer to Nginx wiki.

Alternatively, you could verify the DN in the Nginx config file itself even without delegating to application logic, refer to the Nginx documentation.

server {
   ssl_client_certificate /srv/ssl/self.crt;
   ssl_verify_depth 10;
   ssl_verify_client on;
   proxy_set_header X-SSL-Client-Subject-DN $ssl_client_s_dn;
}

Cipher Suites

While our servers support a wide variety of the Cipher suites to cater to many types and configurations of HTTPS servers, customers can verify whether their HTTPS endpoint is compatible by testing the HTTPS URL via Account Portal.

IP Whitelisting

In addition to verifying the certificate, customers could choose to whitelist the IP addresses that are used to send these callback events. 

Troubleshooting

Please contact the Support Team for additional assistance with troubleshooting.