TLS Certificate Authentication
Securing Couchbase Sync Gateway with TLS Authentication
This content explains how to implement TLS Certificate Authentication for Sync Gateway
Related Security topics: User Authentication | Sync Function | Import filter | Read Access | Write Access
Data Access
Authentication
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.
Authorization
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:
"SSLCert"-
A path to a PEM-format file containing an X.509 certificate or a certificate chain.
"SSLKey"-
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 a 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 1095The 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.cerInstalling 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 certificate based authentication with Sync Gateway, you must first run through the following procedures.
Once the Couchbase Server cluster has been protected by the deployment of root and node certificates described above, a client certificate can be signed by the root certificate, to allow Sync Gateway to access the cluster.
To generate the client certificate, make sure that the Couchbase Server cluster has the expected bucket and RBAC user. Also refer to the Getting Started: Configure Couchbase Server to configure the RBAC user with appropriate privileges for access by a Sync Gateway instance.
Next, follow the instructions in Client Access: Root-Certificate Authorization to create a client certificate that is authorized by the cluster’s root certificate.
After completing the procedure, you will have multiple files generated in the current directory. You will use the following files to configure Sync Gateway:
-
servercertfiles/ca.pem -
servercertfiles/clientcertfiles/travel-sample.pem -
servercertfiles/clientcertfiles/travel-sample.key
X.509 certificate based authentication is enabled on Sync Gateway by specifying the absolute or relative path to each of those files in the configuration file.
Unresolved include directive in modules/ROOT/pages/authentication-certs.adoc - include::example$/x509-config.json[]If the connection is successful, you should see the following in the logs.
[INF] Starting admin server on 127.0.0.1:4985
[INF] Starting server on :4984 ...
[INF] Establishing TLS connection for DCP to destination 127.0.0.1:11207If Sync Gateway cannot connect, you may refer to the Cluster Certificate Errors table.
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.