Channels
About Sync Gateway Channels and their part in data routing and access control for secure cloud-to-edge enterprise data synchronization.
Related Concepts: Access Control Model | Channels | Roles | Sync Function | Users
Concept
Sync Gateway uses Channels defined at collection level to make it easy to share a database’s documents across a large user base whilst retaining effective access control. They serve as a security conduit between the document and a user:
Overview
Channels are defined at the collection level, which means that specific channels can be associated with individual collections of documents. This system allows users with access to a specific channel to access all documents assigned to that channel within that collection.
By defining channels at the collection level, it’s possible to implement detailed access control for different types of data within the database.
You typically will use channels to:
-
Control who can access what
-
Partition your data set
-
Enable users to access just the documents they need
-
Minimize the amount of data synced to mobile devices
Sync Gateway provides two special channels and a channel wildcard character.
Sync Function Examples
Couchbase Sync Gateway defines a Sync Function at the collection level.
Defining at this level helps simplify data management and improve data reliability.
Each collection in the system allows for only one Sync Function, which enables the specification of Access Control rules.
function (doc, oldDoc, meta) {
channel(CollectionName);
}Here the function then calls the channel and passes in the name of the collection (CollectionsName) as an argument.
By default, every document in the collection is automatically assigned to a channel with the same name as the collection. This system automatically creates a channel with the collection’s name. The assignment of all documents to the collection channel is functionally similar to assigning them to the Star Channel.
To override this, use a custom sync function or a Specified Default Sync Function.
function (doc, oldDoc, meta) {
channel(doc.channels);
}Here is the default Sync Function when you have upgraded; it remains the same as the previous version.
Use Case
Imagine a database containing a collection of customer data. Within this collection, channels can be established to provide varying customer data access levels. For example, one channel may provide access to general customer information, while another may allow access to sensitive customer information. Users can then be granted access to one or both channels based on their need to access the associated data.
Configuration
-
Version 3.x
-
legacy
| 1 | Using the Admin REST API: You can provide the admin_channels property using the Admin REST API endpoint (/{tkn-db}/_user/{name}). |
| 2 | Programmatically using Access Grant Document: The Sync Function provides a flexible and secure method for controlling document access and routing. You can program it to derive appropriate access and channel routing information from document properties. Optionally, the access grant can be specified via a designated extended attribute (XATTR) — see: Use XATTRs for Access Grants for how to define the XATTR. |
| 1 | Using the Admin REST API :
You can provide the admin_channels property using the Admin REST API endpoint (/{tkn-db}/_user/{name}). |
| 2 | Programmatically using Access Grant Document:
The Sync Function provides a flexible and secure method for controlling document access and routing. You can program it to derive appropriate access and channel routing information from data embedded within document properties. |
| 3 | File-based Configuration Properties: This is only available in 3.x and is typically used for dev/test environments. You can do it in the Sync Gateway JSON Configuration File (Database Configuration ) by adding the appropriate channel to the user’s admin_channels property — see: user admin_channels. |
System Channels
Public Channel
The Public Channel ('!') — is a channel for publicly available documents. It is ideal for use in making information available across the user community.
You assign a document to the public (!) channel using the channel() function.
Documents assigned to this channel can be accessed by all users; even users assigned no specific channel access.
New users are automatically granted access to the channel.
All Documents Channel
The All Documents Channel ('*') [1] — is a single, internal channel, comprising all documents from all channels.
Assignment to this channel is automatic and implicit. You cannot explicitly assign documents to the channel or remove documents from it.
This channel should not be confused with the use of the All Channels Wildcard in access grants.
All Channels Wildcard
The All Channels Wildcard ('*') — used when granting user access, this wildcard grants access to any document in any channel.
You make dynamic user access grants in the sync function using the access() method.
Granting a user access with the all channels wildcard gives them access to any channel, and any document in any channel, including those from private channels.
Replications by users with all channels wildcard access will pull all documents. Because of this potential for syncing large volumes of data (sync pulls all documents in the bucket), users with all channels wildcard access should use a channel filter to explicitly name the channel(s) to be sync’d.
Note: Users granted access using the all channels wildcard do not inherit requireAccess() rights to any specific channel.
| Always use a filter in conjunction with the all channels wildcard, to avoid sync unnecessarily pulling large numbers of documents to mobile devices. |
You assign documents to channels in the Sync Function.
Channels are created as documents are assigned to them.
Valid channel names consist of text letters [A–Z, a–z], digits [0–9], and a few special characters [= + / . , _ @].
Channel names are case-sensitive.
Channels with no documents assigned to them are empty.
Channel Limits
| Element | Limiting factor | Guidance Limit (Channels) |
|---|---|---|
Channels per document |
The amount of memory consumed by the combined number of channels and access grants must fit within the maximum 1Mb xattr size limit — see: Table 2. |
50 |
Channels per user |
The amount of memory consumed by channels must fit within the 20 MB available on Couchbase Server docs for storing metadata — see: Table 2 |
1,000 |
Sync Metadata Limits
Every time a document is assigned to a new channel, the channel name is appended to that document’s sync metadata.
Therefore, a document’s set of channels is limited by the allowed sync metadata size described in Table 2.
Value of enable_shared_bucket_access |
Size (Mb per Document) |
|---|---|
|
20 |
|
1 |
Sync Gateway will assign a document to a new channel as long as the sync metadata remains under the allowed limit.
What to do when your channel count exceeds the usable space for sync metadata?
In order to lower the sync metadata size per document, you can do one of the following:
-
Lower the number of channels per document.
-
Shorten the channel names. A shorter channel name will occupy less space ("customer==0030169303" vs "cs==0030169303").
-
Lower the revs_limit value. Indeed, a copy of channel metadata is retained for each revision of a document.