Database Security
Using Sync Gateway’s Admin REST API to configure users and roles
Related topics: Overview | Bootstrap | Database | Database Security | Access Control | Import | Inter-Sync Gateway Replication
|
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 provides examples for the /{db}/_role/{name} and /{db}/_user/{name} endpoints. For a full description of all available endpoints, see Database Security.
This page also includes a JSON data model you can use to build your request bodies. See: Schema
Upsert a Role
For complete endpoint details, see /{db}/_role/{name}.
Example
-
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",
"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: 67
{
"name": "newrole",
"admin_channels": ["newrolechannel"]
}| 1 | Add role newrole to the travel25 database |
| 2 | Use Basic Auth to authenticate to an existing RBAC user |
Upsert a User
For complete endpoint details, see /{db}/_user/{name}.
Example
-
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 '{
"password": "pass",
"admin_channels": ["newrole"]
}
'PUT /travel25/_user/newuser HTTP/1.1 (1)
Host: 127.0.0.1:4985
Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk
Content-Type: application/json
Content-Length: 63
{
"password": "pass",
"admin_channels": ["newrole"]
}| 1 | Add user newuser to the travel25 database |
Schema
This section shows the database security configuration settings in schema format. Use these schemas to construct JSON models for the Admin REST API.
The configuration settings described here are provisioned through the Admin REST API. For more information, see 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
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)
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
A set of access grants by scope and collection for a specific collection.
collection_access.{scopename…}
Type: object
An object keyed by scope, containing a set of collections.
collection_access.{scopename…}.{collectionname…}
Type: object
An object keyed by collection name, defines access collections in this scope.
collection_access.{scopename…}.{collectionname…}.admin_channels
Type: array
A list of channels to explicitly grant to the user in this collection.
collection_access.{scopename…}.{collectionname…}.all_channels
Type: array (readOnly)
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)
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)
The last time that the user's JWT channels were updated for this collection.
name
Type: string
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
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
A list of roles to explicitly grant to the user.
all_channels
Type: array (readOnly)
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
A set of access grants by scope and collection for a specific collection.
collection_access.{scopename…}
Type: object
An object keyed by scope, containing a set of collections.
collection_access.{scopename…}.{collectionname…}
Type: object
An object keyed by collection name, defines access collections in this scope.
collection_access.{scopename…}.{collectionname…}.admin_channels
Type: array
A list of channels to explicitly grant to the user in this collection.
collection_access.{scopename…}.{collectionname…}.all_channels
Type: array (readOnly)
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)
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)
The last time that the user's JWT channels were updated for this collection.
disabled
Type: boolean
If true, the user will not be able to login to the account as it is disabled.
email
Type: string
The email address of the user.
jwt_channels
Type: array (readOnly)
The channels that the user has been granted access to through channels_claim for the default collection.
jwt_issuer
Type: string (readOnly)
The issuer of the last JSON Web Token that the user last used to sign in.
jwt_last_updated
Type: string (readOnly)
The last time that the user's JWT roles/channels were updated.
jwt_roles
Type: array (readOnly)
The roles that the user has been added to through roles_claim.
name
Type: string
The name of the user.
User names can only have alphanumeric ASCII characters and underscores.
password
Type: string
The password of the user.
Mandatory. unless allow_empty_password is true in the database configs.
roles
Type: array (readOnly)
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.