You are viewing the documentation for a prerelease version.

View Latest

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.

    Roles are granted access to channels. Any user assigned a role can access any channels (and documents within those channels) the role has been granted access to.

    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 ( PRE 3.0 BETA)
      Configure roles in the Legacy Configuration Properties file.

      Persistent Configuration is enabled by default from 3.0 BETA.

      To continue using legacy Pre-3.0 BETA configuration you should start sync gateway with disable-persistent-config set true either in the configuration file or in Command Line Options.

    Note To use this option in v3.x, you must use the -disable_persistent_config CLI option.

    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.

    Example 1. How to Create a Role
    • 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 BETA 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.