How to Configure Couchbase Grant Permissions

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up couchbase grant permissions by assigning built-in roles to users or groups. You can scope these roles to specific buckets, scopes, or collections. Most teams start by mapping directory groups to broad cluster roles during setup. Over time, engineers request fast fixes and gain wide read and write rights. Broad roles let one bad query change or expose sensitive customer data. How couchbase grant permissions work in practice The database uses role-based control to check every user an

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

You set up couchbase grant permissions by assigning built-in roles to users or groups. You can scope these roles to specific buckets, scopes, or collections. Most teams start by mapping directory groups to broad cluster roles during setup. Over time, engineers request fast fixes and gain wide read and write rights. Broad roles let one bad query change or expose sensitive customer data.

How couchbase grant permissions work in practice

The database uses role-based control to check every user and app action. Admins do not assign raw read or write rights to single accounts. Instead, the system bundles specific rights into predefined roles for daily work. You link a user account or external group to one or more roles.

Data inside the cluster sits in a clear three-level hierarchy. Buckets hold scopes, and scopes hold collections of JSON documents. You can assign a role at the full cluster level for global tasks. You can also narrow that role down to one bucket, scope, or collection. This structure helps teams isolate multi-tenant data or split microservices by scope.

Admins manage these role assignments through the web console, command line, or REST API. You can create local database users or link an external identity provider. When a user logs in, the cluster checks their group and assigned roles. The engine then allows or blocks requests based on those static role boundaries.

Where native database roles fall short

Native roles do a great job of deciding who can log in. They also draw clear walls between different buckets, scopes, and collections. This setup stops a billing app from reading records in a support bucket. Still, static roles cannot inspect what happens inside an allowed collection at runtime.

Once a user has read rights on a collection, they can run any query. Native permissions cannot mask sensitive fields like emails or phone numbers in results. If a collection holds card numbers or national IDs, readers get raw text. You must duplicate data or build custom views to hide those fields.

AI Agent Permissions + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Static roles also stay active 24 hours a day until an admin revokes them. Engineers often keep write roles long after an incident or ticket ends. A tired engineer can run a broad update statement and break production records. Native roles check the collection boundary, not the safety of the statement itself.

Managing day-to-day role sprawl across teams

As clusters grow, teams add dozens of scopes and collections for new features. Admins must update role mappings every time a team adds a new collection. When deadlines loom, admins often grant bucket-wide roles just to unblock developers. Those temporary bucket roles rarely get cleaned up after the launch.

Auditing these static grants across multiple clusters takes hours of manual work. Security teams struggle to prove who ran which query during a shared login session. Shared app accounts make it even harder to tie queries to one person. Teams need a way to check queries and mask data in flight.

Govern statements and responses across databases and APIs

Good config and scoped roles are needed setup. They do not check single queries in flight or mask sensitive fields in returned rows. Across Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, and internal HTTP endpoints, hoop.dev sits inline in the protocol beside each supported service as an open-source proxy, a sidecar for your database or API. For every query or command an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human approval.

First, hoop.dev guardrails block banned queries before they run or hold risky ones for review, and hoop.dev data masking rewrites matched sensitive values in responses in memory. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.

Frequently asked questions

Can you grant permissions to a single collection in Couchbase?

Yes, many data access roles support scoping down to a single collection. You pick the target bucket, scope, and collection when you assign the role.

How do external groups work with Couchbase roles?

You map an external identity group to a role group inside the cluster. Users who log in inherit all roles linked to their external group.

Do native roles hide sensitive fields inside a JSON document?

No, collection roles grant access to the whole JSON document at once. You need field-level masking in flight to rewrite emails or card numbers in results.

The query runs. The emails stay hidden.