A newer version of this documentation is available.

View Latest

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 true either 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.

      Example 1. Assign user to role
      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 _user endpoint (/{tkn-db}/_user/{name} ).

      Specify the roles to be assigned in the admin_roles array.

      $ 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_roles
      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.

      role ("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.

      {
        "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