This page contains security best practices for a production deployment of Couchbase Mobile.

Data Access


In a Couchbase Mobile production deployment, administrators typically perform operations on the Admin REST API. If Sync Gateway is deployed on an internal network, you can bind the adminInterface of Sync Gateway to the internal network. In this case, the firewall should also be configured to allow external connections to the public interface port.

To access the Admin REST API from an entirely different network or from a remote desktop we recommend to use SSH tunneling.


In addition to the Admin REST API, a user can be assigned to a role with additional privileges. The role and the user assigned to it can be created in the configuration file. Then, the Sync Function’s requireRole() method can be used to allow certain operations only if the user has that role.

Data Model Validation

In a NoSQL database, it is the application’s responsibility to ensure that the documents are created in accordance with the data model adopted throughout the system. As an additional check, the Sync Function’s throw() method can be used to reject documents that do not follow the pre-defined data model.

Connection to Sync Gateway

You can run Sync Gateway behind a reverse proxy, such as NGINX, which supports HTTPS connections and route internal traffic to Sync Gateway over HTTP. The advantage of this approach is that NGINX can proxy both HTTP and HTTPS connections to a single Sync Gateway instance.

Sync Gateway also supports serving connections over SSL. To enable SSL, you need to add two properties to the config file:


A path to a PEM-format file containing an X.509 certificate or a certificate chain.


A path to a PEM-format file containing the certificate’s matching private key.

If both properties are present, the server will respond to SSL (and only SSL) over both the public and admin ports. If you want to support both HTTP and HTTPS connections you will need to run two separate instances of Sync Gateway.

How to create an SSL certificate

Certificates are a complex topic. There are basically two routes you can go: request a certificate from a Certificate Authority (CA), or create your own "self-signed" certificate.

Requesting a certificate from a CA

You can obtain a certificate from a trusted Certificate Authority (CA). Examples of trusted CAs include Let’s Encrypt, Thawte or GoDaddy. What this means is that their own root certificates are known and trusted by operating systems, so any certificate that they sign will also be trusted.

Hence, the benefit of a certificate obtained from a trusted CA is that it will be trusted by any SSL client.

Creating your own self-signed certificate

Unlike a CA-signed cert, a self-signed cert isn’t intrinsically trustworthy: a client can’t tell who you are by examining the cert, because no recognized authority has vouched for it. But a self-signed cert is still unique (only you, as the holder of the private key, can operate a server using that cert), and it still allows the connection to be encrypted.

It’s easy to create a self-signed certificate using the openssl command-line tool and these directions. In a nutshell, you just need to run these commands:

$ openssl genrsa -out privkey.pem 2048
$ openssl req -new -x509 -sha256 -key privkey.pem -out cert.pem -days 1095

The second command is interactive and will ask you for information like country and city name that goes into the X.509 certificate. You can put whatever you want there; the only important part is the field Common Name (e.g. server FQDN or YOUR name) which needs to be the exact hostname that clients will reach your server at. The client will verify that this name matches the hostname in the URL it’s trying to access, and will reject the connection if it doesn’t.

The tool will then create two files: privkey.pem (the private key) and cert.pem (the public certificate.)

To create a copy of the cert in binary DER format (often stored in a ".cer" file), do this:

$ openssl x509 -inform PEM -in cert.pem -outform DER -out cert.cer

Installing the certificate

Whichever way you obtained the certificate, you will now have a private key and an X.509 certificate. Ensure that they’re in separate files and in PEM format, and put them in a directory that’s readable by the Sync Gateway process. The private key is very sensitive (it’s not encrypted) so make sure the file isn’t readable by unauthorized processes.

Then just add the "SSLCert" and "SSLKey" properties to your Sync Gateway configuration file.

  "SSLCert": "cert.pem",
  "SSLKey": "privkey.pem",
  "databases": {
    "todo": {
      "server": "http://localhost:8091",
      "users": {"GUEST": {"disabled": false, "admin_channels": ["*"]}}

Start Sync Gateway and access the public port over https on https://localhost:4984.

Connection to Couchbase Server

There are two methods to securely connect a Sync Gateway instance to a Couchbase Server cluster. Each method is discussed below in more detail.

Username and Password

The username and password of the RBAC user are specified in the Sync Gateway configuration file. This method is used in the getting started section.

X.509 Certificates

Sync Gateway 2.1 adds the ability to use X.509 certificates to authenticate against Couchbase Server 5.5 or higher. This functionality can be used instead or in addition to the existing authentication method which is to specify a username and password in the configuration file.

To use x.509 authentication with Sync Gateway, you must first run through the following steps.

  1. Create x.509 certificates for Couchbase Server. See instructions steps 1 - 10.

  2. Configure each Couchbase Server node in the cluster. See instructions steps 11 - 12.

  3. Enable Client Certificate Authentication. See instructions step 13.

After completing step 3, you will have multiple files generated in the current directory. From the generated files, you must copy ca.pem, chain.pem and pkey.key to the machine where Sync Gateway is running.

To connect successfully, you must also ensure the following:

  1. A bucket named travel-sample exists. See instructions.

  2. The RBAC user with the name travel-sample exists has access permissions to the bucket. See instructions.

Then, x.509 can be enabled on Sync Gateway by specifying the absolute or relative path to each of those files in the configuration file.

  "logging": {"debug": {"enabled": true} },
      "use_views": true,
      "cacertpath": "./ca.pem",
      "certpath": "./chain.pem",
      "keypath": "./pkey.key",
      "server": "couchbases://",
      "bucket": "travel-sample"

More detail on the configuration properties for x.509 authentication can be found below.

If the username/password properties are also specified in the configuration file then Sync Gateway will use password-based authentication and also include the client certificate in the TLS handshake.