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:
-
Admin REST API — for the administration and configuration of sync gateway
-
Metrics REST API — for the monitoring of sync gateway performance metrics
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.
| 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. |
|
|
|
|
|
Sync Gateway Application |
Can manage Sync Gateway users and roles, and read and write application data through Sync Gateway. |
|
|
|
|
|
Sync Gateway Application Read Only |
Can read Sync Gateway users and roles, and read application data through Sync Gateway. |
|
|
|
|
|
Sync Gateway Replicator |
Can manage Inter-Sync Gateway Replications. |
|
|
|
|
|
Sync Gateway Dev Ops |
Can manage Sync Gateway node-level configuration, and access Sync Gateway’s /metrics endpoint for Prometheus integration. |
|
|
|
|
|
Sync-Gateway Role |
Can access DB / bucket scoped operations |
|
|
|
|
|
Application Access |
Can access DB / bucket scoped operations |
|
|
|
|
|
Bucket Full Access |
Can access DB / bucket scoped operations |
|
|
|
|
|
Full Admin |
Can access all operations |
|
|
|
|
|
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:
-
-
-admin_interface_authentication=false. -
-metrics_interface_authentication=false.
-
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.
-
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.
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.
| 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 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