A newer version of this documentation is available.

View Latest

Database Security

      +

      Using Sync Gateway’s Admin REST API to configure users and roles

      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

      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}

      If the role does not exist, create a new role otherwise update the existing role.

      Required Sync Gateway RBAC roles:

      • Sync Gateway Architect
      • Sync Gateway Application

      Parameters

      Path Parameters

      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String

      name
      required

      The name of the role.

      String

      Body Parameter

      Name Description Schema

      Body
      optional

      Properties associated with a role

      Role1

      Responses

      HTTP Code Description Schema

      200

      OK

      201

      Created

      404

      Resource could not be found

      HTTP_Error

      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

      If the user does not exist, create a new user otherwise update the existing user.

      Required Sync Gateway RBAC roles:

      • Sync Gateway Architect
      • Sync Gateway Application

      Parameters

      Path Parameters

      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String

      name
      required

      The name of the user.

      String

      Body Parameter

      Name Description Schema

      Body
      optional

      Properties associated with a user

      User1

      Responses

      HTTP Code Description Schema

      200

      Existing user modified successfully

      201

      New user created

      404

      Resource could not be found

      HTTP_Error

      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.

      {
         Role: {
            admin_channels: [],
            all_channels: [],
            collection_access: {
               {scopename...}: {
                  {collectionname...}: {
                     admin_channels: [],
                     all_channels: [],
                     jwt_channels: [],
                     jwt_last_updated: "string"
                  }
               }
            },
            name: "string"
         },
         User: {
            admin_channels: [],
            admin_roles: [],
            all_channels: [],
            collection_access: {
               {scopename...}: {
                  {collectionname...}: {
                     admin_channels: [],
                     all_channels: [],
                     jwt_channels: [],
                     jwt_last_updated: "string"
                  }
               }
            },
            disabled: true,
            email: "string",
            jwt_channels: [],
            jwt_issuer: "string",
            jwt_last_updated: "string",
            jwt_roles: [],
            name: "string",
            password: "string",
            roles: []
         }
      }
      

      Role

      Type

      object

      Description

      Properties associated with a role

      Role.admin_channels

      Type

      array

      Description

      The channels that users in the role are able to access for the default collection.

      Role.all_channels

      Type

      array (readOnly)

      Description

      The channels that the role grants access to for the default collection.

      These channels could have been assigned by the Sync function or using the admin_channels property.

      Role.collection_access

      Type

      object

      Description

      A set of access grants by scope and collection.

      Role.collection_access.{scopename…​}

      Type

      object

      Description

      An object keyed by scope, containing a set of collections.

      Role.collection_access.{scopename…​}.{collectionname…​}

      Type

      object

      Description

      An object keyed by collection name, defines access for the collection.

      Role.collection_access.{scopename…​}.{collectionname…​}.admin_channels

      Type

      array

      Description

      A list of channels to explicitly grant to the user.

      Role.collection_access.{scopename…​}.{collectionname…​}.all_channels

      Type

      array (readOnly)

      Description

      All the channels that the user has been granted access to.

      Access could have been granted through the sync function, roles, or explicitly on the user under the admin_channels property.

      Role.collection_access.{scopename…​}.{collectionname…​}.jwt_channels

      Type

      array (readOnly)

      Description

      The channels that the user has been granted access to through channels_claim.

      Role.collection_access.{scopename…​}.{collectionname…​}.jwt_last_updated

      Type

      string (readOnly)

      Description

      The last time that the user's JWT roles/channels were updated.

      Role.name

      Type

      string

      Description

      The name of the role.

      Role names can only have alphanumeric ASCII characters and underscores.

      User

      Type

      object

      Description

      Properties associated with a user

      User.admin_channels

      Type

      array

      Description

      A list of channels to explicitly grant to the user for the default collection.

      User.admin_roles

      Type

      array

      Description

      A list of roles to explicitly grant to the user.

      User.all_channels

      Type

      array (readOnly)

      Description

      All the channels that the user has been granted access to for the default collection.

      Access could have been granted through the sync function, roles, or explicitly on the user under the admin_channels property.

      User.collection_access

      Type

      object

      Description

      A set of access grants by scope and collection.

      User.collection_access.{scopename…​}

      Type

      object

      Description

      An object keyed by scope, containing a set of collections.

      User.collection_access.{scopename…​}.{collectionname…​}

      Type

      object

      Description

      An object keyed by collection name, defines access for the collection.

      User.collection_access.{scopename…​}.{collectionname…​}.admin_channels

      Type

      array

      Description

      A list of channels to explicitly grant to the user.

      User.collection_access.{scopename…​}.{collectionname…​}.all_channels

      Type

      array (readOnly)

      Description

      All the channels that the user has been granted access to.

      Access could have been granted through the sync function, roles, or explicitly on the user under the admin_channels property.

      User.collection_access.{scopename…​}.{collectionname…​}.jwt_channels

      Type

      array (readOnly)

      Description

      The channels that the user has been granted access to through channels_claim.

      User.collection_access.{scopename…​}.{collectionname…​}.jwt_last_updated

      Type

      string (readOnly)

      Description

      The last time that the user's JWT roles/channels were updated.

      User.disabled

      Type

      boolean

      Description

      If true, the user will not be able to login to the account as it is disabled.

      User.email

      Type

      string

      Description

      The email address of the user.

      User.jwt_channels

      Type

      array (readOnly)

      Description

      The channels that the user has been granted access to through channels_claim.

      User.jwt_issuer

      Type

      string (readOnly)

      Description

      The issuer of the last JSON Web Token that the user last used to sign in.

      User.jwt_last_updated

      Type

      string (readOnly)

      Description

      The last time that the user's JWT roles/channels were updated.

      User.jwt_roles

      Type

      array (readOnly)

      Description

      The roles that the user has been added to through roles_claim.

      User.name

      Type

      string

      Description

      The name of the user.

      User names can only have alphanumeric ASCII characters and underscores.

      User.password

      Type

      string

      Description

      The password of the user.

      Mandatory. unless allow_empty_password is true in the database configs.

      User.roles

      Type

      array (readOnly)

      Description

      All the roles that the user has been granted access to.

      Access could have been granted through the sync function, roles_claim, or explicitly on the user under the admin_roles property.