Read Access
How to handle read-access
The sync function API provides several methods that you can use to validate user access.
Related access-control topics: Sync function | Read access | Write access
Introduction
Every user and role has a set of channels that they are allowed to read.
A user can only read documents that are in at least one of the user’s channels (or the channels of roles that user has.)
After a user is granted access to a new channel, the changes feed incorporates all existing documents in that channel, even those from earlier sequences than the current request’s since parameter.
That way the next pull request retrieves all documents to which the user now has access.
Add Access
User and-or role channel access can be assigned:
-
Directly through the admin API
-
In the configuration file
-
Dynamically, in the Sync Function when a document is accessed
The Sync Function is the preferred method for granting access to channels programmatically.
Sync Function
Calling access(user, channel) grants a user access to a channel. This allows documents to act as membership lists or access-control lists.
A typical example is a document that represents a shared resource (like a chat room or photo gallery) — see: Example 1.
function (doc) {
if (doc.type == "chatroom") { (1)
access(doc.members, (2)
doc.channel_id); (3)
}
}In this example:
| 1 | A chat room is represented by a document with a type property set to chatroom. |
| 2 | The channel_id property names the associated channel, with which the actual chat messages are tagged |
| 3 | The members property lists the users who have access to that channel. |
The access() function can also operate on roles.
If a user name string begins with role: then the remainder of the string is interpreted as a role name.
There’s no ambiguity here, because ":" is an illegal character in a user or role name.
Because anonymous requests are authenticated as the user "GUEST", you can make a channel and its documents public by calling access with a username of GUEST.
Configuration File
A user can be granted access to a channel through the admin_channels property in the configuration file.
Admin REST API
A user can be granted access to a channel through the admin_channels property on the /\{db}/user/{name} admin REST API endpoint.
Revoke Access
Revoking access to a channel can cause a user to lose access to documents, if s/he no longer has access to any channels those documents are in.
However, the replicator does not currently delete such documents that have already been synced to a user’s device (although future changes to those documents will not be replicated.) This is a design limitation of Sync Gateway that may be resolved in the future.
-
A GET request to a document not assigned to one or more of the user’s available channels fails with a 403 error.
-
The
_all_docsproperty is filtered to return only documents that are visible to the user. -
The
_changesproperty ignores requests (via thechannelsparameter) for channels not visible to the user.
Inspect Read Access
You can use the admin REST API to see what channels a user has access to.
Issue an /\{tkn-db}/_user/\{name} request.
Here’s an example of the response.
The output shows that the user pupshaw has access to channels all and hoopy.
{
"admin_channels": [
"all"
],
"admin_roles": [
"froods"
],
"all_channels": [
"all",
"hoopy"
],
"name": "pupshaw",
"roles": [
"froods"
]
}The all_channels property of a user account determines which channels the user can access.
Its value is derived from the union of:
-
The user’s
admin_channelsproperty, which is settable via the admin REST API. -
The channels that user has been given access to by
access()calls from sync functions invoked for current revisions of documents. -
The
all_channelsproperties of all roles the user belongs to, which are themselves computed according to the above two rules.
Replication
By default, Couchbase Lite gets all the channels to which the configured user account has access. This behavior is suitable for most apps that rely on User Authentication and the Sync Function to specify which data to pull for each user.
Optionally, a Couchbase Lite "pull" replication can also specify a comma-separated list of channel names to receive documents from. In this case, the replication from Sync Gateway will only pull documents tagged with those channels. Client apps can use this ability to intelligently sync with a subset of the available documents from the database.