Secure Sync Gateway Access

Overview

TLS is required by default for all communications with Couchbase Server ^[1]. TLS v1.3 is supported as the default protocol.

We strongly recommend always having TLS enabled, although this can be over-ridden for development and testing only.

Additionally, the Admin and Metrics REST API security is also enhanced by the use of Couchbase Server RBAC user credentials to authenticate and authorize access — see: REST API Access

Couchbase Server Connection

By default Sync Gateway requires TLS encryption and the server scheme is specified as couchbases://.

You can set the bootstrap.server_tls_skip_verify flag true to connect to 'default CBS'. But, this must only be done for testing or development purposes.

The content in Table 1 shows the TLS configuration options for sync gateway-Couchbase Server communication. The options include flags that will allow you to override the requirement to use TLS — for use in testing and-or development environments only.

Table 1. Configuration options sync gateway ←→Couchbase Server
Bootstrap Configuration / Command-line flag	Default Behavior	Opt-out
`bootstrap.use_tls_server` CLI: `-bootstrap.use_tls_server`	TLS enabled	Set this `false` in CLI or bootstrap file to turn-off off TLS completely — development and testing only
`bootstrap.server_tls_skip_verify` CLI: `-bootstrap.server_tls_skip_verify`	TLS enabled unless `use_tls_server` opt-out used	Set this `true` in CLI or bootstrap file to skip server verification of certificates (self- or CA-signed) but leave encryption enabled. Do not provide `ca_cert_path` Use for development and testing only
`bootstrap.ca_cert_path` CLI: `-bootstrap.ca_cert_path`	Provides the path to the root CA certificate to verify the certificate chain and hostname of the Couchbase Server cluster	Omit if not required
`bootstrap.x509_cert_path` CLI: `-bootstrap.x509_cert_path`	Provides the path to the client’s certificate to authenticate against Couchbase Server ^[2] 2. 5.5 or above	Omit if not required
`bootstrap.x509_key_path` CLI: `-bootstrap.x509_key_path`	Provides the path to the the client’s private key to authenticate against Couchbase Server ^[3] 3. 5.5 or above	Omit if not required

Behavior

Table 2. Sync Gateway ←→ Couchbase Server behavior
Required Configuration	Default Behavior	Opt-Out Trigger
Use `couchbases://` server scheme Set the certificate and key path: bootstrap.ca_cert_path bootstrap.x509_cert_path bootstrap.x509_key_path	Sync Gateway will error non-secure server schemes (`couchbase:` or `ws:`) unless the opt-out is triggered If a `ca_cert_path` is specified then only certificates from that CA will be accepted. If `ca_cert_path` is omitted If `server_skip_tls_verify=true` Then sync gateway will skip validation of any server cert, but still require encryption. This includes skipping validation of certs that are from a trusted/well known CA If `server_skip_tls_verify=false` Then only certificates from a trusted/well known CA will be accepted	`use_tls_server=false` `server_skip_tls_verify=true` (or included)

For more on creating and installing certificates, see: TLS Certificate Authentication.

Client Connection

Couchbase Lite client applications must be updated to use TLS when connecting to sync gateway nodes running in default mode.

Table 1 shows the TLS configuration options, whilst Table 4 shows the default and opt-out behavior.

Table 3. TLS configuration options
Bootstrap Configuration	Command-line flag	Default	Purpose
`api.https.tls_key_path`	`-api.https.tls_key_path`	nil	Provide the path ^[4] to the TLS private key file. 4. This can be absolute, or relative to the sync gateway executable's directory
`api.https.tls_cert_path`	`-api.https.tls_cert_path`	-	Provide the path to the TLS certificate file.

Omit both options to use plaintext — for development and-or testing only — see the Bootstrap Configuration.

Table 4. TLS behavior
Configuration Properties	Default Behavior	Opt-Out Trigger
api.api.https.tls_cert_path api.api.https.tls_key_path	TLS verification and encryption is enabled by default, unless the opt-out is triggered	Omit from configuration

Running Sync Gateway

As a Service

The serviceconfig.json file uses the couchbases: scheme, with server_skip_tls_verify=true by default, to facilitate testing and development; no TLS validation is done.

Use the following settings to configure TLS:

For more on configuration options, see: Bootstrap Configuration.

Command Line

Use the following command line flags to configure TLS:

-bootstrap.ca_cert_path
-bootstrap.x509_cert_path
-bootstrap.x509_key_path
-bootstrap.server_skip_tls_verify

Sync Gateway will error non-secure server schemes (couchbase: or ws:) unless the opt-out option is true.

Note that you can no longer start sync gateway without providing at least one parameter, as with no configuration file specified, you need to either provide a TLS Cert/Key, or disable TLS.

For more on command line options, see: Command Line Options.

API Topics

Reference

Community

Mobile Forum | Blog | Blog (Mobile) | Tutorials

1. From release 3.0