Users and Roles

You can authorize users and control their access to your database by creating user accounts and assigning roles to users. This article focuses on how to authorize users to be able to access the Sync Gateway and their remote databases.

Sync Gateway users and roles have no relationship to RBAC in Couchbase Server.

Users

The user must be created on Sync Gateway before it can be used for authentication. Users can be created through the Sync Gateway Admin REST API or configuration file.

Admin REST API

You can create a new user by sending a PUT request to /{db}/_user/{name} or by sending a POST request to /{db}/_user, where db is the configured name of the database and name is the user name.

The user credentials (username/password) are passed in the request body.

$ curl -vX POST "http://localhost:4985/mydatabase/_user/" -H "accept: application/json" -H "Content-Type: application/json" -d '{"name": "john", "password": "pass"}'

The Admin REST API is for administrator use only, and hence is not accessible from the clients directly. To allow users to sign up, it is recommended to have an app server sitting alongside Sync Gateway that performs the user validation, creates a new user on this API and then returns the response to the application.

Additionally, this API can be used in conjunction with a 3rd party server for the authentication process (see Custom authentication).

Lastly, Sync Gateway supports OpenID Connect authentication. In this case, Sync Gateway can automatically create users for successfully authenticated users that don’t have an already existing user in Sync Gateway.

Configuration file

User credentials can also be hardcoded in the configuration file. This method is convenient for testing and to get started, otherwise it is generally recommended to use the Admin REST API for a programmatic behavior.

{
  "databases": {
    "mydatabase": {
      "users": { (1)
        "GUEST": {"disabled": true},
        "john": {"password": "pass"}
      }
    }
  }
}

Roles

Roles are named collections of channels. A user account can be assigned to zero or more roles. A user inherits the channel access of all roles it belongs to. This is very much like Unix groups, except that roles do not form a hierarchy.

You access roles through the Admin REST API much like users are accessed, through URLs of the form /{db}/_role/{name}. Role resources have a subset of the properties that users do: name, admin_channels, all_channels.

Roles have a separate namespace from users, so it’s legal to have a user and a role with the same name.

Admin REST API

You can assign a role to a user by sending a PUT request to /{db}/_user/{name} where db is the configured name of the database and name is the user name.

The roles to assign to the user are specified in the admin_roles array.

$ curl -vX POST "http://localhost:4985/mydatabase/_user/" -H "accept: application/json" -H "Content-Type: application/json" -d '{"name": "john", "password": "pass", "admin_roles": ["foo"]}'
Configuration file

A user can also be assigned to a role in the configuration file. This method is convenient for testing and to get started, otherwise it is generally recommended to use the Admin REST API for a programmatic behavior.

{
  "databases": {
    "mydatabase": {
      "users": {
        "GUEST": {"disabled": true},
        "john": {"password": "pass", "admin_roles": ["foo"]}
      }
    }
  }
}