Auto-Purge on Channel Access Revocation
Auto-purge behavior on loss of access to document channels
Related Topics: Concepts | How-to | Sync Function | Use XATTRs for Access Grants
Overview
Users may lose access to documents for many reasons, including:
-
The User loses direct access to channel
-
The User is removed from a role
-
A role the user belongs to is revoked access to channel
Sync Gateway will take the configured action whenever this happens. By default:
-
Sync Gateway syncs will auto-purge documents the user has lost access to — see Sync Gateway
-
Inter-Sync Gateway replications will not auto-purge documents the user has lost access to — Inter-Sync Gateway
Sync Gateway
|
Breaking Change
In Sync Gateway 2.x these documents remain in the local database on channel access loss.
|
By default, when a user loses access to a channel, the next Couchbase Lite Pull replication auto-purges all documents in the channel from local Couchbase Lite databases (on devices belonging to the user) unless they belong to any of the user’s other channels — see: Couchbase Lite Replication — Auto Purge on Channel Access Revocation.
Inter-Sync Gateway
Access Revoked
| This behavior is the reverse of that between Sync Gateway and Couchbase Lite — see: Sync Gateway. |
By default, documents are not auto purged on the active sync gateway even if the user on the passive sync gateway loses channel access.
You can opt-in to auto-purge behavior using the replicator level option purge_on_removal in the REST API — see: replication-purge_on_removal.
Documents will then be auto-purged — on active Sync Gateway nodes that have opted-in — if they do not belong to any of the replicating user’s [1] channels — see: Example 1.
If you turn it on during an existing replication, no revocations occurring prior to that point are retro-actively purged. To have this done, execute a reset for ISGR (on Couchbase Lite a reset checkpoint must be carried out).
Access control policies are only enforced at the remote cluster.
Here the Active Sync Gateway (Local) is running as an admin user with purge_on_removal=true
| Direction | Passive Sync Gateway (Remote) | Expected Sync behavior |
|---|---|---|
Pull |
User revoked access to channel |
Previously synced documents are auto purged on local |
Push |
User revoked access to channel |
Revocation has no impact during a 'push'. No purging will occur. |
PushAndPull |
User revoked access to channel |
When access is revoked on remote, the previously synced documents for User2 are auto-purged on local. Local changes continue to be pushed to remote but rejected by remote |
Access Regained
If a user subsequently regains access to a lost channel then any previously auto-purged documents still assigned to any of their channels are automatically pulled down by the active Sync Gateway — see: Example 2.
If you want to control whether to sync previous auto purged versions of documents (rather than pull down purged documents) then you must also move the documents out of all of the users' channels so they are not synced down again.
Access control policies are only enforced at the remote cluster.
Here the Active Sync Gateway (Local) is running as an admin user with purge_on_removal=true
| Direction | Passive Sync Gateway (Remote) | Expected Sync behavior |
|---|---|---|
Pull |
User REASSIGNED access to channel Sync Function includes
|
Previously purged documents are automatically pulled by local |
Push |
User REASSIGNED access to channel Sync Function includes
|
Config option has no impact. Local changes previously rejected by remote are pushed again with reset action on replicator. Subsequent changes to previously rejected documents are automatically pushed up. |
PushAndPull |
User REASSIGNED access to channel Sync Function includes
|
Documents auto purged on local are automatically pulled again Local changes previously rejected by remote can be pushed again with reset action on replicator. Subsequent changes to previously rejected documents are automatically pushed up. |
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.