Authentication

Couchbase Edge Server supports multiple authentication mechanisms to control client access to the REST API and sync connections.

Overview

By default, all HTTP requests to Couchbase Edge Server require authentication. Couchbase Edge Server supports two independent authentication mechanisms:

Basic authentication — Set username and password credentials in users files.
Mutual TLS (mTLS) — client certificate authentication.

Both mechanisms can be active simultaneously. A client may authenticate using either.

Authentication governs access to the REST API and client sync connections. Replication connections to a remote server use separate credentials configured in the replications block of the configuration file. See Manage Replication with Edge Server for details.

Anonymous Access

Setting enable_anonymous_users: true in the configuration file allows unauthenticated requests from any client.

If you followed the Get Started guide, your configuration uses enable_anonymous_users: true. This is suitable for development and testing only. Disable anonymous access and configure an authentication mechanism before deploying to production.

{
  enable_anonymous_users: true
}

Basic Authentication

Basic authentication uses username and password credentials. You store credentials in a JSON users file and set the path using the top-level users property in the configuration file.

{
  users: "/etc/edge-server/users.json"
}

Users File

The users file is a JSON object where each key is a username and each value describes that user’s credentials and roles. Store passwords as bcrypt hashes, not plaintext.

{
  "alice": {
    "password": "$2y$05$...",
    "roles": ["admin"]
  },
  "bob": {
    "password": "$2y$05$...",
    "roles": ["replicate"]
  }
}

The server reads the users file at startup. You must restart the server for changes to take effect.

For instructions on creating users files and adding users, see Usernames and Passwords.

Never use basic authentication without TLS. Without TLS, attackers can capture passwords as cleartext using packet sniffers.

User Roles

Roles grant additional privileges to a user account. A user without a role can authenticate and view the REST API but cannot manage replications.

Role Privileges

Role	Privileges
`replicate`	Allows access to `/_replicate` to start, stop, and monitor replications.
`admin`	Grants full administrative access, including all privileges granted by `replicate`.

replicate

Allows access to /_replicate to start, stop, and monitor replications.

admin

Grants full administrative access, including all privileges granted by replicate.

Mutual TLS

Mutual TLS (mTLS) requires clients to present a certificate during the TLS handshake. Couchbase Edge Server verifies that a configured Certificate Authority (CA) signs the certificate.

When you set client_cert_path in the https block of the configuration file, all clients must connect using TLS client certificates. The server only accepts certificates signed by the configured CA.

The server records the Common Name (CN) field of the client certificate in server logs for identification purposes only. The server does not match it against entries in the users file, and you do not need to create a corresponding entry in the users file for mTLS clients.

For instructions on configuring mTLS, see Client Certificate Authentication.

Using Basic Auth and mTLS Together

Basic auth and mTLS are independent mechanisms and can be active simultaneously. When you configure both, a client may authenticate using either a valid client certificate or username and password credentials.

Server TLS

Server TLS encrypts the connection between client and server but does not authenticate the client. It’s separate from mTLS; enable it alongside whichever client authentication mechanism you use.

{
  https: {
    tls_cert_path: "./cert.pem",
    tls_key_path: "private.key"
  }
}

For instructions on enabling server TLS and creating a certificate, see Server Authentication with TLS.

For AI agents: