CockroachDB Cloud Access Management Overview and FAQ

This page covers the essential concepts related to access management (authorization) in CockroachDB Cloud. Procedures for managing access are covered in Managing Access in CockroachDB Cloud.

Overview of the CockroachDB Cloud two-level authorization model

The CockroachDB Cloud console, found at https://cockroachlabs.cloud/, is a 'single pane of glass' for managing users, billing, and all functions for administering CockroachDB Serverless and CockroachDB Dedicated clusters. When accessing the console, users must sign in to a CockroachDB Cloud organization (or create a new one).

You can also execute many administrative commands using the ccloud command-line utility and the CockroachDB Cloud API:

• ccloud allows human users to authenticate their terminal via a browser token from the CockroachDB Cloud console.
• The CockroachDB Cloud API allows service accounts to authenticate via API keys, which are issued through the console.
• You can use Terraform to provision users and other aspects of your CockroachDB Cloud clusters. However, note that currently Terraform can only be used to provision admin SQL users, as this is a current limitation of the API, on which Terraform depends.

In CockroachDB Cloud, an organization corresponds to an authorization hierarchy linked to a billing account. Within each CockroachDB Cloud organization, the unit of database functionality is the CockroachDB cluster, which corresponds to a networked set of CockroachDB cluster nodes. SQL operations and data storage are distributed over a cluster. Every cluster belong to an organization.

CockroachDB Cloud has a two-level authorization model:

1. SQL level within a cluster: Each CockroachDB cluster has its own set of SQL users and roles defined in it. Roles grant users permission to execute some set of SQL statements against some set of database resources (like tables, databases) on the cluster.
2. Organization level: Each CockroachDB Cloud organization has a set of roles defined on it, which allow users to perform administrative tasks relating to the management of clusters, organization users, SQL users, and billing.

This page primarily covers the latter, organization level. However, the two levels intersect because administrating SQL-level users on specific clusters within an organization is an organization-level function.

For the main pages covering users and roles at the SQL level within a specific database cluster, see:

• Overview of Cluster Users/Roles and Privilege Grants in CockroachDB
• Managing Cluster User Authorization

Organization user roles

When a user is first added to an organization, they are granted the default role, Org Member, which grants no permissions and only indicates membership in the organization. Org or Cluster Administrators may edit the roles assigned to organization users in the CockroachDB Cloud console's Access Management page, or using the CockroachDB Cloud API / Terraform Provider.

To learn more, refer to Manage organization users.

The following roles may be granted to CockroachDB Cloud organization users within a specific organization:

Org Administrator (legacy)

Org Administrator (legacy) can manage the organization and its members, clusters, and configuration. This role grants the user permissions to perform all critical functions managing a CockroachDB Cloud organization:

• Create or delete a cluster
• Invite team members to the organization
• Manage an organization's users and their roles
• Create and manage SQL users
• Manage billing for the organization
• Restore databases and tables from a CockroachDB Cloud backup
• Delete an organization

Org Developer (legacy)

Org Developer (legacy) can read high-level information for all clusters, and monitor all clusters using DB Console.

Organization Member

This default role is granted to all organization users once they are invited. It grants no permissions to perform cluster or org actions.

Org Administrator

Users with this role on an organization can:

• Invite users to join that organization.
• Create service accounts.
• Grant and revoke roles for both users and service accounts.

This role replaces the Org Administrator (legacy) role, which will be considered deprecated when fine-grained access roles are generally available (GA).

Billing Coordinator

Users with this role in an organization can manage billing for that organization through the CockroachDB Cloud console billing page at https://cockroachlabs.cloud/billing/overview.

Note that billing can also be managed by the Org Administrator (legacy) role.

Cluster Operator

This role can be granted for one or more specific clusters, or for all clusters in the organization. It allows users and service accounts to perform a variety of cluster functions:

• Users with this role can perform the following console operations:

  • View a cluster's Overview page, which displays its configuration, attributes and statistics, including cloud provider, region topography, and available and maximum storage and request units.
  • Manage a cluster's databases from the Databases Page.
  • Scale a cluster's nodes.
  • View and configure a cluster's authorized networks from the Networking Page.
  • View backups in a cluster's Backup and Restore Page.
  • Restore a cluster from a backup.
  • View a cluster's Jobs from the Jobs page.
  • View a cluster's Metrics from the Metrics page.
  • View a cluster's Insights from the Insights page.
  • Upgrade a cluster's CRDB version.
  • View a cluster's PCI-readiness status (Dedicated Advanced clusters only).
  • Send a test alert from the Alerts Page.
  • Configure single sign-on (SSO) enforcement.

• Service accounts with this role can perform the following API operations:

  • Read a cluster summary.
  • Manage Customer-Managed Encryption Keys (CMEK) for Dedicated Clusters
  • Export a cluster's logs.
  • Export a cluster's metrics.
  • View and configure a cluster's Egress Rules.
  • Configure the export of metrics to DataDog or AWS CloudWatch.

This role can be considered a more restricted alternative to Cluster Administrator, as it grants all of the permissions of that role, except that it does not allow users to:

• Manage cluster-scoped roles on organization users.
• Manage SQL users from the cloud console.
• Create or delete a cluster.

Cluster Administrator

This role can be granted for one or more specific clusters, or for all clusters in the organization.

Cluster Administrators can perform all of the Cluster Operator actions, as well as:

• Provision SQL users for a cluster using the console.
• Create Service Accounts.
• Edit cluster-scope role assignments (specifically, the Cluster Administrator, Cluster Operator, and Cluster Developer roles) on users, and service accounts.
• Edit or delete a cluster.
• Cluster Administrators for the whole organization (rather than scoped to a single cluster) can create new clusters.

Cluster Creator

Cluster Creators can create clusters in an organization. A cluster's creator is automatically granted the Cluster Administrator role for that cluster upon creation.

Cluster Developer

Users with this role can view cluster details, allowing them to export a connection string from the cluster page UI, although they will still need a Cluster Administrator to provision their SQL credentials for the cluster.

This role can be granted for specific clusters or for all clusters in the organization.

Service accounts

Service accounts authenticate with API keys to the CockroachDB Cloud API, rather than to the CockroachDB Cloud Console UI.

Service accounts operate under a unified authorization model with organization users, and can be assigned all of the same organization roles as users, but note that some actions are available in the console but not the API, or vice versa (For example, in the Cluster Operator Role).

Legacy service accounts that were created before the updated authorization model was enabled for your cloud organization may have roles assigned under the legacy model: (ADMIN, CREATE, EDIT, READ, DELETE). Legacy service accounts will be considered deprecated once fine-grained access roles are generally available (GA). You should update legacy service accounts to fine-grained access roles, and grant only the required access, according to the principle of least privilege.

Refer to Manage Service Accounts.

Cluster roles for organization users using Cluster SSO

Cluster Single Sign-On (SSO) for CockroachDB Cloud allows authorized organization users to directly access clusters within the organization via ccloud, the CockroachDB Cloud command line interface.

However, because organization users and cluster SQL users are logically separate, a corresponding SQL user must be created for each SSO organization user, on each particular cluster.

This correspondence lies in the SQL user name, which must be in the format sso_{email_name}. Replace '(email_name}' with the portion of the user's email address before @. For example, the SQL username of a user with the email address docs@cockroachlabs.com is sso_docs. If the role is not set up correctly, ccloud prompts you to create or add it. Only an SQL admin can manage SQL users.

FAQ

What role is assigned to new CockroachDB Cloud members? What entitlements are included?

Org Member is the default and only role assignable to new users as they are added to a CockroachDB Cloud organization. This role has most minimum entitlements across all the available roles, including the ability to view the list of available clusters and high-level organization information like ID, Name, Label etc.

What is the minimum access role that can be granted on a cluster?

Cluster Developer is the minimum access role that can be assigned to a cluster user on a cluster. Cluster Developers can view the details of the target cluster and can modify its IP allowlist.

What roles are assigned to the user that creates a CockroachDB Cloud organization and thus becomes the first and only user in that organization?

Org Member, Org Administrator (legacy), and Cluster Admin are assigned to the first and only user in a CockroachDB Cloud organization. This is done to allow the user to perform all actions required to invite other users, create and manage clusters, configure billing, etc.

Once the initial user has added more users to the CockroachDB Cloud organization, it is possible to assign Cluster Admin role to one or more of those users and optionally remove that role from the initial user.

Is it possible to assign more than one role to a user in a CockroachDB Cloud organization?

Yes, it is possible, and often necessary, to assign more than one role to a user. The default minimum access role Org Member is always assigned to every user as long as they’re a part of the CockroachDB Cloud organization. Beyond that, every other assigned role is additive to the overall entitlements of a user. Best example of this is the initial user who is by default assigned the Org Member, Org Administrator (legacy), and Cluster Admin roles when they create the CockroachDB Cloud organization.

Can we follow the least privilege principle by using the roles available in the CockroachDB Cloud authorization model?

Yes, the roles available in the CockroachDB Cloud authorization model allow admins to grant only those entitlements to users that are supposed to map to their intended workflows.

Cluster level roles like Cluster Admin or Cluster Developer allow to perform pertinent actions for one or more clusters, while providing differentiation between admin and non-admin entitlements. Whereas, the Organization level roles like Org Administrator (legacy), Org Developer (legacy) allow admin and non-admin access respectively for the entire organization.

Is the same authorization model used for both service accounts and human users in a CockroachDB Cloud organization?

Yes, for service accounts created after the updated authorization model is enabled for your organization. Service accounts created previously continue to use the previous, less fine-grained authorization model. See Service Accounts.

Can I assign a cluster-level role to a few users such that they have the relevant entitlements on all clusters in the CockroachDB Cloud organization?

Yes, an admin could assign a cluster level role like Cluster Admin or Cluster Developer on the entire CockroachDB DB Cloud organization or on one or more specific clusters. There are two scopes in the authorization model - organization and clusters, with organization being the parent, and clusters being the children in the hierarchy. So if an admin assigns cluster level roles at the organization scope, they are automatically applicable on all clusters in the CockroachDB DB Cloud organization. Such access should be granted only to users who need to work with all clusters.

If an admin removes all role assignments for a particular user, is that user automatically removed from the CockroachDB Cloud organization?

When all role assignments have been removed for a user, they still implicitly have the Org Member role which is granted to each newly-added CockroachDB Cloud member, and the member is not automatically removed from the organization. Refer to: Remove a team member

Which roles grant the ability to add, remove, and manage members in in a CockroachDB Cloud organization?

Users with the Org Administrator (legacy) role are allowed to manage users and roles at both the organization and the cluster scopes. Users with the Cluster Admin role are only allowed to manage role assignments at the cluster scope.

What is the Cluster Creator role useful for when there’s a Cluster Admin role as well?

A user with the Cluster Creator role can create new clusters in the CockroachDB Cloud organization, so this role can be assigned only at the organization scope.

After the cluster is created, its creator is automatically granted the Cluster Admin role on that cluster. If that user already had the Cluster Admin role at the organization scope, this cluster-specific grant appears to have no effect.

This overlap allows admins to give users from different projects or teams access to create and fully manage their own clusters without the ability to manage clusters owned by other projects or teams. For example, two different users from different teams could each be granted the Cluster Creator role so that they can fully manage clusters they own but not clusters owned by anyone else.

Are SQL roles part of the CockroachDB Cloud authorization model?

CockroachDB Cloud has a two-level authorization model:

1. SQL level in a cluster: Each CockroachDB cluster has its own set of SQL users and roles defined in it. Roles grant users permission to execute some set of SQL statements against some set of database resources (like tables, databases) on the cluster.
2. Organization level: Each CockroachDB Cloud organization has a set of roles defined in it, which allow users to perform administrative tasks relating to the management of clusters, organization users, SQL users, and billing.

What methods can an admin use to assign organization-wide and cluster-specific roles to human users and service accounts?

You can use Cloud Console, the Cloud API, or the CockroachDB Terraform provider to assign roles to human users.

To manage roles for service accounts, you must use the Cloud API.

Refer to: - Manage organization users - Manage service accounts

How can we track and audit role-assignment actions in a CockroachDB Cloud organization?

Any user with the Org Administrator role can access Cloud Organization audit logs capability to track when users are added and removed in the CockroachDB Cloud organization, and whenever any role assignment changes are performed for those users.