Roles
About Sync Gateway Roles and their part in secure cloud-to-edge enterprise data synchronization.
Here we introduce the concept of Roles and the part they play in assuring secure access control within Sync Gateway.
Related Concepts: Access Control Model | Channels | Roles | Sync Function | Users
Concept
Roles are named collections of Channels. They enable the grouping together of Users with similar characteristics, which makes the management of large user populations easier.
A Role and a user assigned to a Role is granted access to a channel, a part of collections. The user can then access all documents assigned to that channel. When granting user access to admin channels statically, the user must specify the collection and corresponding channel.
As an entity, roles comprise a name and a list of channels.
Any user associated with a role inherits the right to access any of the channels in the role’s list. This provides a convenient way to associate multiple channels with multiple users.
| Roles have a separate namespace from users, so it’s possible to have a user and a role with the same name. |
Provisioning
The creation of roles is optional. It depends on the use case whether there is a need to logically group users.
You can create and-or manage roles using the following options
-
Admin REST API:
Roles are created via the Sync Gateway Admin REST API — see: Admin REST API. -
File-based Configuration Properties [1]
Note To use this option in v3.x, you must use the
-disable_persistent_configCLI option.Configure roles in the Legacy Configuration Properties file.
Note that removing a role effectively revokes access to the channel that role is associated with and may mean users will lose access to required documents.
-
Admin REST API
-
File-based Configuration Properties
| This is the default recommended option starting 3.0.. |
Create a new role using the /{tkn-db}/_role/ endpoint.
$ curl -vX POST "http://localhost:4985/mydatabase/_roles/" -H
"accept: application/json" -H "Content-Type: application/json" -d
'{"name": "Edge1", "admin_channels": ["channel1", "channel3"]]}' (1)| 1 | Here we add the Edge1 role. |
Create roles by hardcoding them in the Legacy Pre-3.0 Configuration. This method is convenient for testing and to get started. It is recommended to use the REST API for production systems.
{
"databases": {
"mydatabase": {
"roles": { (1)
"Edge1": {"admin_channels": ["channel1", "channel3"]}, (2)
"Edge2": {"admin_channels": ["channel2", "channel3"]},
"GUEST": {"disabled": true}
}
}
}
}| 1 | databases.$db.users |
| 2 | Here we add the Edge1 role. |