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
In 3.0 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}
Use this convenience endpoint to upsert a Sync Gateway role.
Sync Gateway Roles Required (CBS 7.0.2 Developer Preview):
-
Sync Gateway Architect
-
Sync Gateway Application
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
db |
Database name |
string |
Path |
name |
Role name, may contain any combination of the characters When passing a role name in a URL path it must be escaped again using percent encoding for example if a role is created with the name "0|59", the '|' character must first be percent-encoded resulting in "0%7C59". When using the same role name in a URL path it must be percent-encoded a second time resulting in "0%257C59" |
string |
Body |
role |
The message body is a JSON document that contains the following objects. |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
200 - OK - Operation successful |
No Content |
201 |
201 - OK - Create Operation successful |
No Content |
401 |
401 - Unauthorized - Error validating credentials |
No Content |
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 |
Use this method to create or update a user
Sync Gateway Roles Required (CBS 7.0.2 Developer Preview):
-
Sync Gateway Architect
-
Sync Gateway Application
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
db |
Database name |
string |
Path |
name |
User’s name, may contain contain any combination of the characters When passing a user name in a URL path it must be escaped again using percent encoding for example if a user is created with the name "0|59", the '|' character must first be percent-encoded resulting in "0%7C59". When using the same user name in a URL path it must be percent-encoded a second time resulting in "0%257C59" |
string |
Body |
user configuration data |
Provision the user configuration data in JSON format in the body |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
200 - OK - Operation successful |
No Content |
201 |
201 - OK - Create Operation successful |
No Content |
401 |
401 - Unauthorized - Error validating credentials |
No Content |
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.