How to Assign Users to Roles
How to assign a Sync Gateway User one or more roles for secure access control in cloud-to-edge enterprise data synchronization.
Sync Gateway Users and Roles are a key part of a flexible approach to data routing and access control.
Related topics: Create Role | Create User | Add Role to User | Allow Access | Verify Access | Write Access
Process
You can assign (or remove) users to (or from) roles using any of the following mechanisms:
-
Admin REST API
Assign a user to a role via the Admin REST API -
Configuration Properties file (Pre v3.x+)
Roles can be configured within using the DB section — see: Legacy Pre-3.0 Configuration.
Persistent Configuration is enabled by default from 3.0.
To continue using legacy Pre-3.0 configuration you should start Sync Gateway with disable-persistent-config set
trueeither in the configuration file or in Command Line Options. -
Sync Function
Programmatically assign users to roles.
Removing a role effectively revokes access to the channel that role is associated with. This may mean users will lose access to required documents.
- Admin REST API
-
The recommended method from 3.0 Assign a user to a role by sending a PUT request to the Admin REST API
_userendpoint (/{tkn-db}/_user/{name} ).Specify the roles to be assigned in the
admin_rolesarray.bash$ curl -vX PUT "http://localhost:4985/mydatabase/_user/{user}" -H (1) "accept: application/json" -H "Content-Type: application/json" -d '{ "admin_roles": ["Edge1"]}' (2)1 {user} is the user name to be updated, e.g. "Edge1User" 2 Include the role that the user is to be assigned to in admin_rolesSee also: /{tkn-db}/_role/{name}
- Sync Function
-
You can also use the Sync Function’s role() function to assign users to roles programmatically.
In this use case, where role assignment is done dynamically via the sync function, the role(s) to which user is assigned can be identified in two ways:
-
By document content — the role can be derived or specified as a property within the document body.
-
By user defined XATTR (3.0+) — the role can be specified within a special user-defined XATTR associated with the document — see: Use XATTRs for Access Grants
Note that both role and user must already exist. Nonexistent roles don’t cause an error, but have no effect on the user’s access privileges.
javascriptrole ("Edge1User", "role:Edge1"); role ("Edge2User", "role:Edge2":); -
- File-based Configuration Properties
-
Persistent Configuration is enabled by default from 3.0.
To continue using legacy Pre-3.0 configuration you should start Sync Gateway with disable-persistent-config set true either in the configuration file or in Command Line Options.
Add the role the user is to be assigned to in the configuration file. This method is convenient for testing and to get started. Use the Admin REST API for production systems.
json{
"databases": {
"mydatabase": {
"users": { (1)
"GUEST": {"disabled": true},
"Edge1User": {"password": "pass", "admin_roles": ["Edge1"], (2)
"admin_channels": ["RandomChannel"]},
"Edge2User": {"password": "pass", "admin_roles": ["Edge2"]}
}
}
}
}
| 1 | Within users find the user you want to assign to a role |
| 2 | Add the role the user is to be assigned to in admin_roles — see: databases.$db.users.$user.admin_roles |