Couchbase Server 7.0 Beta is now available with some additional enhancements to strengthen the security of the platform.  Couchbase Server has allowed fine grain controls of user access to the platform with role-based access control (RBAC) security for administrators since version 4.5 and for all users since version 5.0.  Couchbase Collections were introduced as a developer preview feature in Couchbase Server 6.5 and are now fully supported in Couchbase Server 7.0.     A new important announcement is the introduction of collections support to RBAC Security.

Couchbase RBAC security roles were previously divided into 2 categories. 

  • Administration and Global: Associated with cluster-wide privileges. Some of these roles are for administrators; who might manage cluster-configurations; or read statistics; or enforce security. Others are for users and user-defined applications that require access to specific, cluster-wide resources.
  • Per Bucket: Associated with one or more buckets. These roles support the reading and writing of bucket-settings; the management of services, indexes, and replication procedures; and access to data.

For example, you may have given read access to a bucket named Travel to a trusted hotel search engine called Acme Co. with a user named acme using a command like this in the CLI of a Linux based cluster.  (You may need to adjust the paths if using another platform.)

What this would do is allow your hotel search partner Acme Co. to access all of the data your company is storing in the Travel Couchbase Bucket.  This might include orders, inventory and other pieces of data for not only Hotels but Airlines and other travel products.  Following the principle of least privilege, what if we wanted to limit what data Acme Co. has access to, instead of allowing them access to all travel data in our company ?   

Collections allow documents in a Couchbase Bucket to be organized,  first into scopes,  where a ‘Scope’ is similar to a ‘Schema’ in a relational database; and next the scope is subdivided into individual ‘Collections’, similar to how a ‘Table’ would be structured in a traditional relational database.  

The namespace within each scope is independent of others, hence you can have the same collection names in different scopes. Similarly, document keys need to be unique only within a collection and hence documents with the same key can exist in different collections.  Before collections, it was common to organize Couchbase documents based on key prefixes, such as Orders::Europe::Customer1.  Collections provide much more flexibility in the document keys than was available previously.

Collections Diagram

For seamless upgrade, and for backwards compatibility, every bucket has a ‘_default’ scope and the ‘_default’ scope has a ‘_default’ collection. The _default collection provides backward compatibility as a direct reference to the bucket will automatically map to the _default collection. Also, on upgrade all existing data will automatically go to the _default collection. 

While the _default collection is provided as a backward compatibility mechanism, it is recommended that new applications should be written using named collections.  As you can see, collections allow for additional options to organize data in a Couchbase Server cluster.

Going back to the previous example,  what if we wanted to only allow Acme Co. to see the hotel data only, instead of all travel data across the company ?   With collections, we can now limit the confines of Acme’s access to only the ‘scope’ of our choosing.  For example, say Acme Co. needed to check the inventory of available hotel rooms, we can narrow their RBAC role down to the Hotel collection inside the Inventory scope within the Travel bucket.

RBAC Security Explained

How do scopes and collections work with RBAC security roles in the database?  A user who has access to a bucket will inherit access to the children scopes and collections of that bucket.  Likewise, a user who has access to a scope will inherit access to the children collections but not the parent bucket. 

Here’s some examples of how the scope of the roles work with collections.

Role Description
data_reader[*] Can read data in every bucket, including every scope and collection, cluster-wide.
data_reader[foo] Can read data in every scope and collection with-in only the bucket foo
data_reader[foo:bar] Can read data in every collection with-in the scope bar of the bucket foo.
data_reader[foo:bar:baz] Can read data only in the collection baz which is located in the scope bar of the bucket foo.
Collections RBAC Example 1

Collections RBAC Security Example 1

Collections RBAC Example 2

Collections RBAC Security Example 2





For Acme Co, the CLI command is very similar to the earlier example, but instead of setting the RBAC to a bucket, we just need to adjust it to allow only a single scope and collection  

We want to allow the acme user access to the Hotel collection inside of the Inventory scope, so in this case the role would be data_reader[Travel:Inventory:Hotel]

What are the list of user access roles that can have a scope and collection defined ? 

  1. Application Access
  2. Data Reader
  3. Data Writer
  4. Data DCP Reader
  5. Data Monitoring
  6. (FTS) Search Reader
  7. Query Select
  8. Query Update
  9. Query Insert
  10. Query Delete
  11. Query Manage Index
  12. Analytics Select

    We’ve also added the ability to provide a Manage Collections in Scope role to allow a user to add and remove collections in a specific scope on a bucket.

Practical Hands-on RBAC Security Example with Couchbase Server 7.0 Beta

Now for some more hands-on examples you can try out in the Couchbase Server 7.0 Beta.  Again, I’m using a linux based cluster, so you may need to adjust the paths if using another platform.  You’ll need to be running the Data, Query and Index services for this example.

Load the travel-sample bucket into your cluster. 

Create some additional collections in the bucket, we’ll use the _default scope.  You’ll need to use a bucket administrator user or higher privileges to create the new collections. 

You can also see these collections in the Couchbase Server Web UI.

Screenshot of Couchbase Server 7.0 Buckets

Screenshot of the bucket view in Couchbase Server 7.0 Beta


Couchbase Server 7.0 Scopes and Collections Screenshot

Screenshot of Scopes and Collection view in Couchbase Server 7.0 Beta

Next we’ll load data into each of the collections based on a field which already exists in the documents, called “type”.  The document “type” field is matching to the new collections we have just created. The data is copied into the collection using N1QL from the command line.  We need to be careful to escape characters the shell would try to execute such as backticks.

If you run into any issues with the formatting, getting the command to run, here’s an example image of what the command should look like. 

Screenshot N1QL Hotel Collection Populate

Let’s create a primary index on the hotel collection as an administrator.

Now let’s get a list of all users / roles

We currently only have the built-in Administrator and no additional users. So the output from the command is empty, as expected. 

Let’s create a user,  John Doe who has a data reader and query select role on the hotel collection, which is located in the _default scope.

Again you can do this from the Web UI as well.

Couchbase Server 7.0 Screenshot of user roles

RBAC User Role screenshot in Couchbase Server 7.0 Beta

Now we can verify that John Doe has the permissions specific to the hotel collection.  When John attempts to read from the entire travel-sample bucket, he gets a permission denied error.

Now this time let’s select 5 hotels as John from just the hotel collection of the travel-sample bucket, which John does have access to.

As shown in the examples, you can qualify a Data Reader and Query Select role with a scope and collection confinement. 

Have fun and secure your collections with our new RBAC security functionality !

Availability and Duration of Beta


What’s new

Release notes

Additional Blogs

Scopes and Collections for Modern Multi-Tenant Applications: Couchbase 7.0

Couchbase Transactions with N1QL

Get the Beta of Community Edition and Enterprise Edition


Couchbase 7 Beta is available for both Enterprise and Community Editions. Everyone can download the software from

Customer support is available via your regular support channels, while Community support is available through the Couchbase forums at


Posted by Ian McCloy, Principal Product Manager, Couchbase

Ian McCloy is a Principal Product Manager for Couchbase and lives in the United Kingdom. He focuses on security features across the Couchbase portfolio of on-prem, cloud and edge products. Ian has a vast range of experience as a Software Engineer, Technical Support Engineer, Quality Assurance Engineer and Systems Administrator. Ian has lead global technical teams for the majority of his 20 year professional career and holds several patents in the areas of information security, virtualisation and hardware design.


  1. Hi~ Thank you for your post.
    I think there’s a typo here, so I’m leaving a comment.
    Let’s create a user, John Doe who has a data reader and query select role on the hotel collection, which is located in the _default collection.

    I think _default Collection >>> _default Scope

    It’s right?

    Once again, thank you for your helpful post.

  2. Ian McCloy, Principal Product Manager, Couchbase November 20, 2020 at 5:25 am

    Hello ckdgur. Happy to hear that the blog post is useful. Good spotting, that is indeed a typo. I’ve corrected it now. Also thanks a lot for giving the Couchbase 7 Beta a spin !

Leave a reply