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

    In 3.0 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}

    Use this convenience endpoint to upsert a Sync Gateway role.

    Sync Gateway Roles Required (CBS 7.0.2 Developer Preview):

    • Sync Gateway Architect

    • Sync Gateway Application

    Parameters

    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Path

    name
    required

    Role name, may contain any combination of the characters [a-z A-Z 0-9 - + . @ %], when creating a role any other characters must be percent encoded, see: https://en.wikipedia.org/wiki/Percent-encoding.

    When passing a role name in a URL path it must be escaped again using percent encoding for example if a role is created with the name "0|59", the '|' character must first be percent-encoded resulting in "0%7C59". When using the same role name in a URL path it must be percent-encoded a second time resulting in "0%257C59"

    string

    Body

    role
    optional

    The message body is a JSON document that contains the following objects.

    Role_model

    Responses

    HTTP Code Description Schema

    200

    200 - OK - Operation successful

    No Content

    201

    201 - OK - Create Operation successful

    No Content

    401

    401 - Unauthorized - Error validating credentials

    No Content

    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

    Use this method to create or update a user

    Sync Gateway Roles Required (CBS 7.0.2 Developer Preview):

    • Sync Gateway Architect

    • Sync Gateway Application

    Parameters

    Type Name Description Schema

    Path

    db
    required

    Database name

    string

    Path

    name
    required

    User’s name, may contain contain any combination of the characters [a-z A-Z 0-9 - + . @ %], when creating a user any other characters must be percent encoded, see: https://en.wikipedia.org/wiki/Percent-encoding.

    When passing a user name in a URL path it must be escaped again using percent encoding for example if a user is created with the name "0|59", the '|' character must first be percent-encoded resulting in "0%7C59". When using the same user name in a URL path it must be percent-encoded a second time resulting in "0%257C59"

    string

    Body

    user configuration data
    optional

    Provision the user configuration data in JSON format in the body

    User_model

    Responses

    HTTP Code Description Schema

    200

    200 - OK - Operation successful

    No Content

    201

    201 - OK - Create Operation successful

    No Content

    401

    401 - Unauthorized - Error validating credentials

    No Content

    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.