How to Configure Couchbase User Roles

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up couchbase user roles by linking accounts to built-in cluster permissions. These roles decide who can read, write, or manage buckets, scopes, and collections. Many teams start by giving broad cluster admin rights to speed up work. That choice gives every developer full power to read or delete live data. Over time, shared accounts and wide permissions create big security risks for the team. How couchbase user roles work in a cluster The database uses role-based control to check what

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 user roles by linking accounts to built-in cluster permissions. These roles decide who can read, write, or manage buckets, scopes, and collections. Many teams start by giving broad cluster admin rights to speed up work. That choice gives every developer full power to read or delete live data. Over time, shared accounts and wide permissions create big security risks for the team.

How couchbase user roles work in a cluster

The database uses role-based control to check what each account can do. Admins create a user account and pick where the database checks that identity. Local accounts store their name and secret right inside the cluster. External accounts check with a central directory service when a person logs in.

Next, the admin links one or more roles to that user account. You can also place users into groups and link roles to the group. Group mapping saves time when people join or leave the engineering team. A role can cover the whole cluster or just one bucket.

Fine-grained roles go even deeper to target one scope or one collection. Data reader roles let a person or app pull documents from a bucket. Data writer roles let them add, change, or remove documents in that space. Query roles govern who can run statements or build new indexes on data. Admin roles allow people to add nodes, run backups, or change security rules.

How to plan role scope for people and apps

Good role setup starts by splitting human users from app accounts. Each app should have its own account limited to its own data scope. If an app only reads user profiles, give it a reader role there. Do not give an app account the right to drop buckets or indexes.

Human users need different rules based on their daily job tasks. Support engineers might only need read roles on non-sensitive collections to check bugs. Database admins need cluster management roles, but they do not always need data read rights. Splitting cluster upkeep from data reading keeps private records safer during daily work.

Teams should also check role assignments every few months to clean up old accounts. When a project ends, remove the roles tied to that old workspace. Using directory groups makes this cleanup much faster for the security team.

User Provisioning (SCIM) + Lambda Execution Roles: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native roles solve and what they leave open

Built-in roles do a great job of blocking strangers from the cluster. They make sure a billing app cannot change records in an inventory bucket. They also stop a read-only user from dropping a live collection by mistake.

Still, static roles only check who logs in and which bucket they touch. Once a user has a data reader role, they can read every field. The database returns raw emails, phone numbers, and card numbers in query results. Native roles cannot rewrite matched sensitive fields in results on the fly.

Static roles also stay active 24 hours a day until an admin removes them. An engineer who needs write rights for ten minutes keeps them all week. Plus, shared roles make it hard to see which person ran a bad query. Native role checks decide who gets in, not what each live command does.

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 limit a Couchbase role to one collection?

Yes, many data and query roles let you pick a bucket, scope, and collection. This setup keeps a user or app inside one small slice of data. Cluster-wide admin roles still apply across the whole system and cannot shrink.

What is the difference between local and external users?

Local users have their login names and passwords stored inside the database cluster. External users log in through an outside directory system that your company manages. Both user types use the exact same built-in roles once they log in.

Do data reader roles hide sensitive document fields?

No, a data reader role grants read rights to the whole document in scope. If a document holds card numbers or national IDs, the query returns them. Hiding specific fields in results requires an extra layer that rewrites matched data.

The query runs. The emails stay hidden.