Get Started with the Edge Server REST API
To get started with the Couchbase Edge Server REST API, you must specify the interface and authentication options using the Edge Server configuration file.
Interface
To specify the interface for REST-based access to Edge Server, use the interface top-level property in the configuration file.
This property is a string and may contain either or both of the following components:
-
An IP address
-
A port number, preceded by a colon (
:)
The interface property is optional.
If the IP address is not specified, it defaults to 0.0.0.0, that’s all interfaces.
If the port number is not specified, it defaults to 59840.
For testing, it may be useful to set the IP address to 127.0.0.1, which allows only clients on the same device to connect.
Authentication
For an overview of Couchbase Edge Server authentication mechanisms, see Authentication.
You must specify authentication options to enable clients to connect securely to the REST API.
Server Authentication with TLS
To enable TLS, you must create an asymmetric key-pair and a certificate containing the public key. Then set the certificate path and matching private-key path in the Edge Server configuration. These files can use Privacy-Enhanced Mail (PEM) format, which is ASCII (American Standard Code for Information Interchange) text, or Distinguished Encoding Rules (DER) format, which is binary.
Add these to the https property of the configuration file:
| Name | Description | Schema |
|---|---|---|
tls_cert_path |
Path of file containing TLS server certificate. |
string |
tls_key_path |
Path of file containing matching private key. |
string |
client_cert_path |
Path of file containing Certificate Authority (CA) certificate for clients. See Client Certificate Authentication (mTLS). |
string |
{
https: {
tls_cert_path: "./cert.pem",
tls_key_path: "./private.key"
}
}If you encrypted the private-key file, the server prompts you for its password on stdin. If unencrypted, restrict the file permissions so that only the server administrator can access it.
Create a Self-Signed Certificate
| In production you’re recommended to use a certificate generated by a well-known Certificate Authority (CA) like Let’s Encrypt or Digicert. |
For convenience of development and testing, you can create a self-signed TLS server certificate by using the --create-cert flag, as follows.
couchbase-edge-server --create-cert <hostname.example.com> <CertFile> <KeyFile>The first argument can be one of two things:
-
The hostname clients use to reach the server. This becomes the certificate’s X.509
CNattribute. This must match the hostname in the sync URL used by clients, or the client’s TLS handshake fails. -
One or more
name=valuepairs, separated by commas. Eachnameis an X.509 Distinguished Name or Subject Alternative Name component, such asOUorrfc822Name; see RFC 4519 and RFC 5280. You must include theCNattribute, as described above.
The <CertFile> and <KeyFile> arguments specify the paths for the certificate and key files the command creates.
(If they already exist, the command overwrites them.)
In this mode the program exits after creating the files, without starting the server.
You can then add these filenames to the https property of your configuration file as described previously.
The certificate uses a 4096-bit RSA key-pair and has a lifetime of one year.
No client accepts a self-signed certificate unless you turn off validation or explicitly tell it to trust that certificate.
With the curl command, for example, you can add the --insecure flag to turn off validation.
|
If another Edge Server is to sync with this server, you need to add the pinned_cert attribute to its replication configuration.
See Manage Replication with Edge Server.
If a Couchbase Lite application is to sync with this server, it needs a copy of the server’s certificate, and set this as a pinned certificate in the replicator attributes. See the Couchbase Lite documentation for details.
Client Certificate Authentication (mTLS)
To configure TLS client authentication (mTLS), add a client_cert_path property to the configuration file’s https object, whose value is the path to the file containing the client CA certificate — that’s, the master certificate that signs each client’s certificate.
The server’s TLS handshake then requires a client certificate, and verifies that it’s signed by the configured CA.
Couchbase Edge Server derives the client’s username from the Common Name (CN) field of the certificate.
{
https: {
tls_cert_path: "./cert.pem",
tls_key_path: "./private.key",
client_cert_path: "./ca.pem"
}
}Usernames and Passwords
Couchbase Edge Server also supports HTTP Basic authentication. To use HTTP Basic authentication, you need to specify the user names and their passwords.
| WARNING: Never use basic authentication in production without TLS, or else clients transmit passwords in cleartext and packet-sniffers can capture them. |
The top-level users configuration property is a string containing the path to a JSON file of accounts.
That file should contain a JSON object, whose keys are user names, and whose values are objects of the form:
| Name | Description | Schema |
|---|---|---|
password |
bcrypt hash of password. |
string |
roles |
List of role-name strings. |
array |
| This file’s schema is https://packages.couchbase.com/couchbase-edge-server/users_schema.json. |
The users file reads at startup. Changes take effect only after the server restarts.
All HTTP requests require either Basic authentication or a client certificate, unless the top-level enable_anonymous_users property sets to true.
Passwords
For security, Couchbase Edge Server stores users' passwords in hashed form.
A bcrypt hash is represented as a 60-character string that starts with a $, something like $2y$05$, followed by base64-encoded data.
The easy way to add a username and password is to use the --add-user CLI flag.
couchbase-edge-server --add-user <userfile> <username>The command prompts you to enter the user’s password (twice).
Optional flags for this mode:
-
--create— the command creates the user file if it does not exist. -
--role <role>— the command assigns the user the named role (adminorreplicate). -
--password PASSWORD— the command uses this password instead of reads it from stdin. (This is less secure since the shell history captures the password, and other processes using tools likepscan see it, but it’s useful in scripts.)
If you want to edit the users file by hand, you can create a bcrypt hash by running the htpasswd command, which is available from your Linux package manager, or pre-installed on macOS:
htpasswd -nB <username>This prompts for the password, then outputs the username and hash separated by a :.
Copy the part after the : and paste it into the new user’s password property value.
User Roles
The roles property of a user object adds privileges to that user account.
Available user roles are:
-
"replicate"— allows user access/_replicateto start, stop, and monitor replications. -
"admin"— allows everything. Currently no different from"replicate".
Examples
This example creates a self-signed certificate called cert.cer and a keyfile called key.pem.
The CN attribute for the certificate is set to localhost.
./couchbase-edge-server --create-cert CN=localhost cert.cer key.pemThis example creates a users file called users.json and adds a user called seatuser.
./couchbase-edge-server --add-user users.json seatuser --createOn running the command, you’re prompted to enter and confirm a password for the new user.