Database Security

Using Sync Gateway’s Admin REST API to configure users and roles

Pre-3.0 Legacy Configuration Equivalents

This content describes configuration for Sync Gateway 3.0 and higher — for legacy configuration, see: Legacy Pre-3.0 Configuration

Introduction

Use the Admin REST API _user and _role endpoints to provision and manage sync gateway users through persistent configuration changes.

This page introduces the Create or Update a Role and Create or Update a User endpoints for convenience — see Database Security for a full description of the endpoints available.

It also includes a JSON-data model, you can use to build your request bodies. See: Schema

Create or Update a Role

PUT /{db}/_role/{name}

For detailed parameters and response information, see: /{db}/_role/

Example using Named collections

Curl
HTTP

curl --___location --request PUT 'http://127.0.0.1:4985/travel25/_role/newrole' \ (1)
--header 'Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk' \ (2)
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "newrole",
    "collection_access": {
      "scopename": {
          "collectionname": {
               "admin_channels": ["newrolechannel"]
          }
      }
   }
}'

PUT /travel25/_role/newrole HTTP/1.1 (1)
Host: 127.0.0.1:4985
Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk (2)
Content-Type: application/json
Content-Length: 134

{
    "name": "newrole",
    "collection_access": {
      "scopename": {
          "collectionname": {
               "admin_channels": ["newrolechannel"]
          }
      }
   }
}

1	Add role `newrole` to the `travel25` database and the `scopename` scope and `collectionname` collection
2	Note we are using Basic Auth to authenticate to an existing RBAC user

Example using Default collections

Curl
HTTP

curl --___location --request PUT 'http://127.0.0.1:4985/travel25/_role/newrole' \ (1)
--header 'Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk' \ (2)
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "newrole",
    "collection_access": {
      "_default": {
          "_default": {
               "admin_channels": ["newrolechannel"]
          }
      }
   }
}'

PUT /travel25/_role/newrole HTTP/1.1 (1)
Host: 127.0.0.1:4985
Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk (2)
Content-Type: application/json
Content-Length: 132

{
    "name": "newrole",
    "collection_access": {
      "_default": {
          "_default": {
               "admin_channels": ["newrolechannel"]
          }
      }
   }
}

1	Add role `newrole` to the `travel25` database using the `_default` scope and collection
2	Note we are using Basic Auth to authenticate to an existing RBAC user

For complete role management operations, see: /{db}/_role/[Role management API Reference]

Create or Update a User

PUT /{db}/_user/{username} (1)

1	where `{db}` is the Sync Gateway database and `{username}` is the name for the new user

For detailed parameters and response information, see: {db}/_user/{name}[Create User] or /{db}/_user/{name}[Update User]

Example using Named collections

Curl
HTTP

curl --___location --request PUT 'http://127.0.0.1:4985/travel25/_user/newuser' \ (1)
--header 'Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "newuser",
    "password": "pass",
    "collection_access": {
      "scopename": {
          "collectionname": {
               "admin_channels": ["newuserchannel"]
          }
      }
   }
}'

PUT /travel25/_user/newuser HTTP/1.1 (1)
Host: 127.0.0.1:4985
Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk
Content-Type: application/json
Content-Length: 154

{
    "name": "newuser",
    "password": "pass",
    "collection_access": {
      "scopename": {
          "collectionname": {
               "admin_channels": ["newuserchannel"]
          }
      }
   }
}

1	Add user `newuser` to the `travel25` database with access to `scopename.collectionname`

Example using Default collections

Curl
HTTP

curl --___location --request PUT 'http://127.0.0.1:4985/travel25/_user/newuser' \ (1)
--header 'Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "newuser",
    "password": "pass",
    "collection_access": {
      "_default": {
          "_default": {
               "admin_channels": ["newuserchannel"]
          }
      }
   }
}'

PUT /travel25/_user/newuser HTTP/1.1 (1)
Host: 127.0.0.1:4985
Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk
Content-Type: application/json
Content-Length: 152

{
    "name": "newuser",
    "password": "pass",
    "collection_access": {
      "_default": {
          "_default": {
            "admin_channels": ["newuserchannel"]
        }
      }
   }
}

1	Add user `newuser` to the `travel25` database using the default scope and collection

For complete user management operations, see: /{db}/_user/{name}[User management API Reference]

Schema

This section shows Sync Gateway’s database security configuration settings in schema format for convenience in constructing JSON models for use in the Admin REST API.

The configuration settings described here are provisioned through the Admin REST API — see as shown in Database Security.

Role

{
   admin_channels: ["string"...],
   all_channels: ["string"...],
   collection_access: {
      {scopename...}: {
         {collectionname...}: {
            admin_channels: ["string"...],
            all_channels: ["string"...],
            jwt_channels: ["string"...],
            jwt_last_updated: "string"
         }
      }
   },
   name: "string"
}

`admin_channels`

Type: array
Description: A list of channels to explicitly grant to the role for the default collection. See collection_access for channels in named collections.

`all_channels`

Type: array (readOnly)
Description: All the channels that the role has been granted access to for the default collection.

These channels could have been assigned by the Sync function or using the admin_channels property.

`collection_access`

Type: object
Description: A set of access grants by scope and collection for a specific collection.

`collection_access.{scopename…}`

Type: object
Description: An object keyed by scope, containing a set of collections.

`collection_access.{scopename…}.{collectionname…}`

Type: object
Description: An object keyed by collection name, defines access collections in this scope.

`collection_access.{scopename…}.{collectionname…}.admin_channels`

Type: array
Description: A list of channels to explicitly grant to the user in this collection.

`collection_access.{scopename…}.{collectionname…}.all_channels`

Type: array (readOnly)
Description: All the channels that the user has been granted access to in this collection.

Access could have been granted through the sync function, roles, or explicitly on the user under the admin_channels property.

`collection_access.{scopename…}.{collectionname…}.jwt_channels`

Type: array (readOnly)
Description: The channels that the user has been granted access to through channels_claim for this collection.

`collection_access.{scopename…}.{collectionname…}.jwt_last_updated`

Type: string (readOnly)
Description: The last time that the user's JWT channels were updated for this collection.

`name`

Type: string
Description: The name of the role.

Role names can only have alphanumeric ASCII characters and underscores.

User

{
   admin_channels: ["string"...],
   admin_roles: ["string"...],
   all_channels: ["string"...],
   collection_access: {
      {scopename...}: {
         {collectionname...}: {
            admin_channels: ["string"...],
            all_channels: ["string"...],
            jwt_channels: ["string"...],
            jwt_last_updated: "string"
         }
      }
   },
   disabled: false,
   email: "string",
   jwt_channels: ["string"...],
   jwt_issuer: "string",
   jwt_last_updated: "string",
   jwt_roles: ["string"...],
   name: "string",
   password: "string",
   roles: ["string"...]
}

`admin_channels`

Type: array
Description: A list of channels to explicitly grant to the user for the default collection. See collection_access for channels in named collections.

`admin_roles`

Type: array
Description: A list of roles to explicitly grant to the user.

`all_channels`

Type: array (readOnly)
Description: All the channels that the user has been granted access to for the default collection. See collection_access for channels in named collections.

Access could have been granted through the sync function, roles, or explicitly on the user under the admin_channels property.

`collection_access`

Type: object
Description: A set of access grants by scope and collection for a specific collection.

`collection_access.{scopename…}`

Type: object
Description: An object keyed by scope, containing a set of collections.

`collection_access.{scopename…}.{collectionname…}`

Type: object
Description: An object keyed by collection name, defines access collections in this scope.

`collection_access.{scopename…}.{collectionname…}.admin_channels`

Type: array
Description: A list of channels to explicitly grant to the user in this collection.

`collection_access.{scopename…}.{collectionname…}.all_channels`

Type: array (readOnly)
Description: All the channels that the user has been granted access to in this collection.

Access could have been granted through the sync function, roles, or explicitly on the user under the admin_channels property.

`collection_access.{scopename…}.{collectionname…}.jwt_channels`

Type: array (readOnly)
Description: The channels that the user has been granted access to through channels_claim for this collection.

`collection_access.{scopename…}.{collectionname…}.jwt_last_updated`

Type: string (readOnly)
Description: The last time that the user's JWT channels were updated for this collection.

`disabled`

Type: boolean
Description: If true, the user will not be able to login to the account as it is disabled.

`email`

Type: string
Description: The email address of the user.

`jwt_channels`

Type: array (readOnly)
Description: The channels that the user has been granted access to through channels_claim for the default collection.

`jwt_issuer`

Type: string (readOnly)
Description: The issuer of the last JSON Web Token that the user last used to sign in.

`jwt_last_updated`

Type: string (readOnly)
Description: The last time that the user's JWT roles/channels were updated.

`jwt_roles`

Type: array (readOnly)
Description: The roles that the user has been added to through roles_claim.

`name`

Type: string
Description: The name of the user.

User names can only have alphanumeric ASCII characters and underscores.

`password`

Type: string
Description: The password of the user.

Mandatory. unless allow_empty_password is true in the database configs.

`roles`

Type: array (readOnly)
Description: All the roles that the user has been granted access to.

Access could have been granted through the sync function, roles_claim, or explicitly on the user under the admin_roles property.

Errors

This section shows possible error responses returned by the Admin REST API.

Property		Schema
error required	The error name.	String
reason required	The error description.	String

Property

Schema

error
required

The error name.

String

reason
required

The error description.

String

API Topics

Reference

Community

Mobile Forum | Blog | Blog (Mobile) | Tutorials

Database Security

Introduction

Create or Update a Role

Example using Named collections

Example using Default collections

Create or Update a User

Example using Named collections

Example using Default collections

Schema

Role

admin_channels

all_channels

collection_access

collection_access.{scopename…​}

collection_access.{scopename…​}.{collectionname…​}

collection_access.{scopename…​}.{collectionname…​}.admin_channels

collection_access.{scopename…​}.{collectionname…​}.all_channels

collection_access.{scopename…​}.{collectionname…​}.jwt_channels

collection_access.{scopename…​}.{collectionname…​}.jwt_last_updated

name

User

admin_channels

admin_roles

all_channels

collection_access

collection_access.{scopename…​}

collection_access.{scopename…​}.{collectionname…​}

collection_access.{scopename…​}.{collectionname…​}.admin_channels

collection_access.{scopename…​}.{collectionname…​}.all_channels

collection_access.{scopename…​}.{collectionname…​}.jwt_channels

collection_access.{scopename…​}.{collectionname…​}.jwt_last_updated

disabled

email

jwt_channels

jwt_issuer

jwt_last_updated

jwt_roles

name

password

roles

Errors

Related Content

`admin_channels`

`all_channels`

`collection_access`

`collection_access.{scopename…}`

`collection_access.{scopename…}.{collectionname…}`

`collection_access.{scopename…}.{collectionname…}.admin_channels`

`collection_access.{scopename…}.{collectionname…}.all_channels`

`collection_access.{scopename…}.{collectionname…}.jwt_channels`

`collection_access.{scopename…}.{collectionname…}.jwt_last_updated`

`name`

`admin_channels`

`admin_roles`

`all_channels`

`collection_access`

`collection_access.{scopename…}`

`collection_access.{scopename…}.{collectionname…}`

`collection_access.{scopename…}.{collectionname…}.admin_channels`

`collection_access.{scopename…}.{collectionname…}.all_channels`

`collection_access.{scopename…}.{collectionname…}.jwt_channels`

`collection_access.{scopename…}.{collectionname…}.jwt_last_updated`

`disabled`

`email`

`jwt_channels`

`jwt_issuer`

`jwt_last_updated`

`jwt_roles`

`name`

`password`

`roles`