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
We use the Admin REST API _user
and _role
endpoints to provision and manage sync gateway users through persistent configuration changes.
This content 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}
If the role does not exist, create a new role otherwise update the existing role.
Required Sync Gateway RBAC roles:
- Sync Gateway Architect
- Sync Gateway Application
Parameters
Path Parameters
Name | Description | Schema |
---|---|---|
db |
The name of the database to run the operation against. |
String |
name |
The name of the role. |
String |
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 | Note we are using Basic Auth to authenticate to an existing RBAC user |
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 |
If the user does not exist, create a new user otherwise update the existing user.
Required Sync Gateway RBAC roles:
- Sync Gateway Architect
- Sync Gateway Application
Path Parameters
Name | Description | Schema |
---|---|---|
db |
The name of the database to run the operation against. |
String |
name |
The name of the user. |
String |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Existing user modified successfully |
|
201 |
New user created |
|
404 |
Resource could not be found |
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 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: [], all_channels: [], collection_access: { {scopename...}: { {collectionname...}: { admin_channels: [], all_channels: [], jwt_channels: [], jwt_last_updated: "string" } } }, name: "string" }, User: { admin_channels: [], admin_roles: [], all_channels: [], collection_access: { {scopename...}: { {collectionname...}: { admin_channels: [], all_channels: [], jwt_channels: [], jwt_last_updated: "string" } } }, disabled: true, email: "string", jwt_channels: [], jwt_issuer: "string", jwt_last_updated: "string", jwt_roles: [], name: "string", password: "string", roles: [] } }
Role
- Type
-
object
- Description
-
Properties associated with a role
Role.admin_channels
- Type
-
array
- Description
-
The channels that users in the role are able to access for the default collection.
Role.all_channels
- Type
-
array (readOnly)
- Description
-
The channels that the role grants access to for the default collection.
These channels could have been assigned by the Sync function or using the
admin_channels
property.
Role.collection_access
- Type
-
object
- Description
-
A set of access grants by scope and collection.
Role.collection_access.{scopename…}
- Type
-
object
- Description
-
An object keyed by scope, containing a set of collections.
Role.collection_access.{scopename…}.{collectionname…}
- Type
-
object
- Description
-
An object keyed by collection name, defines access for the collection.
Role.collection_access.{scopename…}.{collectionname…}.admin_channels
- Type
-
array
- Description
-
A list of channels to explicitly grant to the user.
Role.collection_access.{scopename…}.{collectionname…}.all_channels
- Type
-
array (readOnly)
- Description
-
All the channels that the user has been granted access to.
Access could have been granted through the sync function, roles, or explicitly on the user under the
admin_channels
property.
Role.collection_access.{scopename…}.{collectionname…}.jwt_channels
- Type
-
array (readOnly)
- Description
-
The channels that the user has been granted access to through channels_claim.
Role.collection_access.{scopename…}.{collectionname…}.jwt_last_updated
- Type
-
string (readOnly)
- Description
-
The last time that the user's JWT roles/channels were updated.
Role.name
- Type
-
string
- Description
-
The name of the role.
Role names can only have alphanumeric ASCII characters and underscores.
User
- Type
-
object
- Description
-
Properties associated with a user
User.admin_channels
- Type
-
array
- Description
-
A list of channels to explicitly grant to the user for the default collection.
User.admin_roles
- Type
-
array
- Description
-
A list of roles to explicitly grant to the user.
User.all_channels
- Type
-
array (readOnly)
- Description
-
All the channels that the user has been granted access to for the default collection.
Access could have been granted through the sync function, roles, or explicitly on the user under the
admin_channels
property.
User.collection_access
- Type
-
object
- Description
-
A set of access grants by scope and collection.
User.collection_access.{scopename…}
- Type
-
object
- Description
-
An object keyed by scope, containing a set of collections.
User.collection_access.{scopename…}.{collectionname…}
- Type
-
object
- Description
-
An object keyed by collection name, defines access for the collection.
User.collection_access.{scopename…}.{collectionname…}.admin_channels
- Type
-
array
- Description
-
A list of channels to explicitly grant to the user.
User.collection_access.{scopename…}.{collectionname…}.all_channels
- Type
-
array (readOnly)
- Description
-
All the channels that the user has been granted access to.
Access could have been granted through the sync function, roles, or explicitly on the user under the
admin_channels
property.
User.collection_access.{scopename…}.{collectionname…}.jwt_channels
- Type
-
array (readOnly)
- Description
-
The channels that the user has been granted access to through channels_claim.
User.collection_access.{scopename…}.{collectionname…}.jwt_last_updated
- Type
-
string (readOnly)
- Description
-
The last time that the user's JWT roles/channels were updated.
User.disabled
- Type
-
boolean
- Description
-
If true, the user will not be able to login to the account as it is disabled.
User.email
- Type
-
string
- Description
-
The email address of the user.
User.jwt_channels
- Type
-
array (readOnly)
- Description
-
The channels that the user has been granted access to through channels_claim.
User.jwt_issuer
- Type
-
string (readOnly)
- Description
-
The issuer of the last JSON Web Token that the user last used to sign in.
User.jwt_last_updated
- Type
-
string (readOnly)
- Description
-
The last time that the user's JWT roles/channels were updated.
User.jwt_roles
- Type
-
array (readOnly)
- Description
-
The roles that the user has been added to through roles_claim.
User.name
- Type
-
string
- Description
-
The name of the user.
User names can only have alphanumeric ASCII characters and underscores.
User.password
- Type
-
string
- Description
-
The password of the user.
Mandatory. unless
allow_empty_password
istrue
in the database configs.
User.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.