A newer version of this documentation is available.

View Latest

Secure API Access

      +

      Sync Gateway REST API Access
      Shows how to access Sync Gateway APIs

      Related REST API topics: Public REST API | Admin REST API | Metrics REST API

      Overview

      Sync Gateway provides secure access to its REST APIs, namely the:

      Each REST API is accessed through a different, user-specifiable, TCP port. This makes it easy to control their physical exposure, perhaps to keep the Admin REST API secure behind your firewall.

      Sync gateway 3.0.0 brings additional optional but default layers of security through enforcing TLS encryption for all API traffic and Couchbase Server Role-Based Access Control (RBAC) authorization and authentication for all Admin and Metrics API users.

      RBAC user authentication enables Secure Administration of sync gateway clusters. This is critical in cloud native deployments. The use of different RBAC roles for uses also provides secure and fine-grained access control — for more on the available roles see Sync Gateway RBAC Roles

      TLS

      TLS is enforced by default for all Couchbase Server connections in 3.0. For more on TLS, see: enforcing TLS encryption.

      Secure Administration

      Secure Administration is on by default.

      In order to submit Admin or Metrics REST API requests you should create specific Couchbase Server users for that purpose. You will then provide a valid set of Couchbase Server credentials for these RBAC-users in each API request.

      Authenticated users will have access to Admin and-or Metrics API functionality, application data and configuration settings.

      Sync Gateway RBAC Roles

      Couchbase Server makes a number of RBAC roles available for Sync Gateway use. Each user’s access-level will depend on its allocated role.

      The currently available roles will vary depending on the Couchbase Server release version — see: Table 1.

      When referencing the Admin REST API you will see that each endpoint states the role (or roles) able to use it — you can find a cross-reference of endpoints and required roles in RBAC Role - Endpoint Cross-Reference.

      Note that the only role available for community-edition users is the Full Admin role.

      Table 1. Sync gateway role availability by release
      Role Capability 7.1.0 7.0.2 DP1 6.1 - 7.0 5.5 - 6.0 5.1

      Sync Gateway Architect

      Can manage Sync Gateway databases and users, and access Sync Gateway’s metrics endpoint. This user cannot read application data.

      yes

      yes

      no

      no

      no

      Sync Gateway Application

      Can manage Sync Gateway users and roles, and read and write application data through Sync Gateway.

      yes

      yes

      no

      no

      no

      Sync Gateway Application Read Only

      Can read Sync Gateway users and roles, and read application data through Sync Gateway.

      yes

      yes

      no

      no

      no

      Sync Gateway Replicator

      Can manage Inter-Sync Gateway Replications.
      This user cannot read application data.

      yes

      yes

      no

      no

      no

      Sync Gateway Dev Ops

      Can manage Sync Gateway node-level configuration, and access Sync Gateway’s /metrics endpoint for Prometheus integration.

      yes

      yes

      no

      no

      no

      Sync-Gateway Role

      Can access DB / bucket scoped operations

      no

      no

      yes

      no

      no

      Application Access

      Can access DB / bucket scoped operations

      no

      no

      yes

      yes

      no

      Bucket Full Access

      Can access DB / bucket scoped operations

      no

      no

      yes

      yes

      yes

      Full Admin

      Can access all operations

      no

      no

      yes

      yes

      yes

      1For more information on Developer Previews, see Developer Preview Mode and Features

      For more on creating Couchbase Server users see the Couchbase Server content here Server — Manage Users and Roles.

      Secure Administration Opt-out

      You can choose to disable Secure Administration by using these bootstrap configuration settings or CLI flags:

      LDAP Authentication

      Authentication against an external system such as LDAP is possible through Couchbase Server.

      However, this can increase the risk of performance and or connection issues — for more on this see the Couchbase Server documentation LDAP Users and Authentication

      Port Configuration

      You can change the ports used for any of the interface types by editing its bootstrap configuration property, for example, api.admin_interface — as shown in Example 1 — and restarting the sync gateway node. The default ports are shown in Table 2.

      Example 1. Configuring ports
      • Admin

      • Metrics

      • Public

        api: {
          "admin_interface": ":4985", (1)
          "admin_interface_authentication": true,
      
          // ... additional group properties
      
        },
        api: {
          "metrics_interface": ":4986", (1)
          "metrics_interface_authentication": true,
      
          // ... additional group properties
      
        },
        api: {
          "public_interface": ":4984", (1)
      
          // ... additional group properties
      
        },
      1 The value of the interface property is a string consisting of a colon followed by a port number (for example, :4985). You can also include a host name or numeric IP address before the colon to bind only to that network interface.

      As a useful special case, the IP address 127.0.0.1 binds to the loopback interface, making the port unreachable from any other host. This is the default setting for the admin interface.

      Network Port Requirements

      Sync Gateway uses specific ports for communication with the outside world, mostly Couchbase Lite databases replicating to and from Sync Gateway — see Table 2 for details.

      Table 2. Sync Gateway Network Port Requirements
      Port Description

      4984

      Public port. External HTTP port used for replication with Couchbase Lite databases and other applications accessing the REST API on the Internet.

      The Public REST API is used for client replication. The default port for the Public REST API is 4984.

      4985

      Admin port. Internal HTTP port for unrestricted access to the database and to run administrative tasks.

      The Admin REST API is used to administer user accounts and roles. It can also be used to look at the contents of databases in superuser mode. The default port for the Admin REST API is 4985. By default, the Admin REST API is reachable only from localhost for safety reasons.

      4986

      Metrics port. By default 4986 is the internal HTTP port designated for providing access to Sync Gateway’s Metrics REST API. Like the admin port, it is bound to 127.0.0.1 by default.

      The Metrics REST API returns Sync Gateway metrics, in JSON and-or Prometheus-compatible formats, for performance monitoring and-or diagnostic purposes,

      For more on configuration see api.admin_interface