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