CockroachDB Cloud Access Management (Authorization) Overview

This page covers the essential concepts related to access management (authorization) in CockroachDB Cloud. Procedures for managing access are covered in Managing Users, Roles, and Service Accounts in CockroachDB Cloud. For Frequently Asked Questions, refer to CockroachDB Cloud FAQ.

Overview of the CockroachDB Cloud 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 belongs to an organization.

CockroachDB Cloud has a hierarchical authorization model, where roles can be assigned at different scopes:

1. Organization: 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.
2. Folder: If an organization is enrolled in CockroachDB Cloud Folders (Limited Access), roles can be assigned on folders. Role inheritance is transitive; a role granted on the organization or a folder is inherited by descendent resources.
3. Cluster: Each CockroachDB cluster defines its own set of SQL users and roles which grant them permission to execute SQL statements on the cluster.

The levels within the hierarchy 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, refer to:

• 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 CockroachDB Cloud organization roles can be granted:

Organization Member

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

Org Administrator

Org Administrators can:

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

Org Administrators automatically receive email alerts about planned cluster maintenance and when CockroachDB Cloud detects that a cluster is overloaded or experiencing issues. In addition, Org Administrators can subscribe other members to the email alerts, and can configure how alerts work for the organization.

This role can be granted only at the scope of the organization.

This role replaces the Org Administrator (legacy) role, which is considered deprecated.

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.

Cluster Operator

Cluster Operators can 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.
  • Access the DB Console.
  • Configure a cluster's maintenance window.

• 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.

This role can be granted at the scope of the organization, on an individual cluster, or on a folder. If granted on a folder, it is inherited on the folder's clusters, descendent folders, and their descendants.

Cluster Administrator

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.
• Access the DB Console.
• Configure a cluster's maintenance window.

This role can be granted at the scope of the organization, on an individual cluster, or on a folder. If granted on a folder, it is inherited on the folder's clusters, descendent folders, and their descendants.

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.

This role can be granted at the scope of the organization or on a folder. If granted on a folder, it is inherited on the folder's clusters, descendent folders, and their descendants.

Cluster Developer

Users with this role can view cluster details and access the DB Console, 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 at the scope of the organization, on an individual cluster, or on a folder. If granted on a folder, it is inherited on the folder's clusters, descendent folders, and their descendants.

Folder Admin

This role is available only when your organization is enrolled in the Folders Limited Access.

Folder Admins can create, rename, and move, or delete folders where they are granted the role, and they can also manage access to these folders. This role can be granted at the level of the organization or on a specific folder. If granted on a specific folder, the role is inherited by descendent folders.

An Org Administrator role can grant any user or service account the Folder Admin role.

To create a cluster in a folder, the user must also have the Cluster Administrator or Cluster Creator role on that folder. To delete a cluster, the user must have the Cluster Administrator role, either on the cluster directly or by inheritance.

This role can be granted at the scope of the organization, on an individual cluster, or on a folder. If granted on a folder, it is inherited on the folder's clusters, descendent folders, and their descendants.

Folder Mover

This role is available only when your organization is enrolled in the Folders Limited Access.

Folder Movers can rename folders and move resources within them, but cannot create or delete folders, and cannot manage access to folders or clusters. To move a folder, you must have permission on both the current location and the target location. Folder Movers and Folder Admins have this permission.

A user with the Org Administrator or the Folder Admin role can grant themselves, another user, or a service account the Folder Mover role.

This role can be granted at the scope of the organization, on an individual cluster, or on a folder. If granted on a folder, it is inherited on the folder's clusters, descendent folders, and their descendants.

Legacy Roles (deprecated)

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 information for all clusters, and monitor all clusters using DB Console.

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:

• The ADMIN role allows the service account full authorization for the organization, where the service account can create, modify, and delete clusters.
• The CREATE role allows the service account to create new clusters within the organization.
• The DELETE role allows the service account to delete clusters within the organization.
• The EDIT role allows the service account to modify clusters within the organization.
• The READ role allows the service account to get details about clusters within the organization.

Update legacy service accounts to roles in the new authorization model, 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.