Manage Users, Roles, and Service Accounts

On this page

This page details procedures for managing CockroachDB Cloud access to CockroachDB Cloud. Before proceeding, it is recommended to review the concepts related to the two levels of CockroachDB Cloud access management model (the organization level and the SQL level in a cluster), which are detailed in CockroachDB Cloud Access Management Overview and FAQ.

Access management tasks for the organization level are performed in the CockroachDB Cloud console Access Management page, found at https://cockroachlabs.cloud/access. This page allows organization administrators to invite users to the CockroachDB Cloud organization, create service accounts, and manage the access roles granted to both. Users with Cluster Admin role on a cluster can also manage the access role grants on that cluster. Roles can be granted at different scopes (levels) of the resource hierarchy.

Access management tasks for SQL level in a cluster are a bit distributed. SQL users on particular clusters can be created in the console's 'SQL user' page for a specific cluster, found at https://cockroachlabs.cloud/cluster/<CLUSTER ID>/users, or with the ccloud command line utility's cluster user create command, or with a SQL client. However, the SQL roles that govern permissions in the cluster for SQL users must be managed with a SQL client. Furthermore, SQL users created with the console or with ccloud utility are granted the admin SQL role on the cluster by default; this makes it important from a security perspective to immediately modify this user if needed, revoking the admin role and replacing it with a SQL role with privileges required for its task, according to the principle of least privilege.

See Manage SQL users on a cluster

Manage your organizations

An organization allows you to manage your clusters under a shared billing account and collaborate with team members. You can belong to multiple organizations, like a personal organization, an enterprise organization for evaluating CockroachDB Cloud, and another enterprise organization with CockroachDB Cloud credits to map to all application clusters.

To switch to a different organization:

Log in to the console at https://cockroachlabs.cloud/ or your organization's custom domain.
From the drop-down box in the top-right corner, select the organization you want to access.

The settings and information about the organization are found on the Information page. The organization ID and organization label used by the ccloud CLI are listed on that page.

Manage an organization's users

Invite team members to an organization

An Org Administrator can invite team members to CockroachDB Cloud. To invite team members:

If you are a member of multiple organizations, navigate to the organization to which you want to invite a team member. You can navigate to the correct organization by using the drop-down box in the top-right corner.
On the Access Management page, under the Members tab, click Invite.
In the Email Address field, enter the email address of the team member you want to invite. By default, a user is assigned the Organization member role; this default role grants no access. After the user is invited, you will be able to grant additional roles.
If required, you could invite multiple users at the same time by adding a row per email address using + Add Member.

It is also possible to enable autoprovisioning for your organization, which removes the need to invite team members.

Change a team member's roles

On the Access Management page, locate the team member's details whose role you want to change. The Role column lists current organization roles granted to each user. See: Organization User Roles
In the row for the target member, click the three-dots Action button and select Edit Roles.
A number of fine-grained roles can be assigned to a given user. Each role is represented by a row. Each row has a scope, which is one of Organization, the name of a particular folder, or the name of a particular cluster. If the role is Cluster Administrator, Cluster Operator, or Cluster Developer, assigning it at the organization scope means that it applies to all clusters in the organization.

Note:

When editing roles for a group in the Groups tab, the fields for that group's inherited roles are read-only, because inherited roles cannot be edited directly. Instead, you must either remove the role from the parent group from which it is inherited, or remove the member from the parent group.

Warning:

An Org Administrator can revoke the Org Administrator role from their own user, but cannot subsequently re-grant the administrator role to themselves.

Remove a team member

On the Access Management page, locate the team member you want to remove.
In the Action column, click the three dots to view the allowed actions.
Click Remove Member and confirm.

Revoke a pending invite

On the Access Management page, locate the team member's details whose pending invite you want to revoke.
In the Action column, click the three dots to view the allowed actions.
Click Revoke Invite.

Delete an email address

This is not currently available through the CockroachDB Cloud Console. To remove an email address from your account, contact Support.

Delete an organization

Warning:

Deleting an organization will delete all clusters and user data within the organization. This action cannot be reversed. To delete a single cluster instead, see Cluster Management.

If you are sure you want to delete the organization, proceed with the following steps:

Navigate to the Information page for the organization you want to delete.
Click Delete.
Enter the name of the organization.
Click Delete.

You will be automatically logged out of your account.

Manage service accounts

The access management model for service accounts is unified with the user model. This means that service accounts may have all of the same access roles. However, service accounts and users still differ in the actions they can perform: only users can access the console, and only service accounts can access the API. The console and API differ in functionality.

Create a service account

On the Access Management page, select the Service Accounts tab.
Click Create.
Enter a Account name and Description.
Create and export an API key.
Confirm creation of the service account.

Note:

Service accounts, like users, are given only the Org Member role by default upon creation. This role grants no access in the organization. After it is created, you can grant additional roles to the service account.

Edit roles on a service account

On the Access Management page, select the Service Accounts tab.
In the row for the target service account, click, click the three-dots Action button and select Edit Roles.
A number of fine-grained roles can be assigned to a given service account. These are the same roles that can be assigned to users. Each role is represented by a row. Each row has a scope, which is either Organization or the name of a particular cluster. If the role is Cluster Administrator, Cluster Operator, or Cluster Developer, assigning it at the organization scope means that it applies to all clusters in the organization.

The fields for a group's inherited roles are read-only, because inherited roles cannot be edited directly. Instead, you must either remove the role from the parent group from which it is inherited, or remove the member from the parent group.

API access

Each service account can have one or more API keys. API keys are used to authenticate and authorize service accounts when using the API. All API keys created by the account are listed under API Access.

We recommend creating service accounts with the principle of least privilege, and giving each application that accesses the API its own service account and API key. This allows fine-grained access to the cluster.

Create API keys

To create an API key:

On the Access Management page, select the Service Accounts tab.
Click the service account for which you want to create an API key to bring up the Service Account Details page.
Click Create API Key.
Enter the API key name and click Create. The name should identify how the API key will be used. For example, you could name your API key for the application that will use the key.
Copy the Secret key and store it in a secure location. There is a Copy button to the right of the displayed secret key that will copy the secret key to your OS clipboard.

The secret key contains the API key and secret. It should never be shared or publicly accessible. Anyone with the secret key can use the API with the permissions of the service account.

Warning:

The secret key will not be available after closing the Create API key dialog. If you have lost your secret key, you should delete the API key and create a new one.
Click Done.

Delete API keys

To delete an API key associated with a service account:

On the Access Management page, select the Service Accounts tab.
Click the service account for which you want to create an API key to bring up the Service Account Details page.
Click the Action button for the API key ID in the API Access table.
Select Delete.
In the Delete API key dialog enter the name of the service account to confirm the delete operation, then click Delete.

Edit API key names

To change the API key name for an existing API key:

On the Access Management page, select the Service Accounts tab.
Click the service account for which you want to create an API key to bring up the Service Account Details page.
Find the API key ID in the API Access table.
Click the Action button.
Select Edit.
In the Edit API key name dialog modify the API key name and click Save changes.

Create a SQL user

Warning:

By default, a new SQL user created using the UI or Cloud API is granted the SQL admin role. An admin SQL user has full privileges for all databases and tables in the cluster, and can create additional SQL users and manage their privileges. When possible, it is best practice to limit each user's privileges to the minimum necessary for their tasks, in keeping with the Principle of Least Privilege (PoLP).

Refer to: Manage SQL users on a cluster

Note:

Only Org Administrators and Cluster Administrators can create SQL users and issue credentials.

Navigate to your cluster's SQL Users page in the Security section of the left side navigation.
In the left navigation bar, click SQL Users.
Click Add User. The Add User dialog displays.
Enter a username and click Generate & Save Password.
Copy the generated password to a secure location, such as a password manager.
Click Close.

Currently, all new users are created with SQL admin privileges. For more information and to change the default settings, see Grant privileges to a SQL user and Use SQL roles to manage access.

Once you have connected to the cluster's SQL client, you can create a new user.

To create a new user, use the CREATE USER ... WITH PASSWORD statement:

> CREATE USER <username> WITH PASSWORD '<password>';

Note:

Be sure to create a password for each new user. Without a password, or being enrolled in cluster single sign-on (SSO), a user cannot connect to the cluster or access the DB Console. To add or change a password for a user, use the ALTER USER statement.

View all SQL users in your cluster

To view a list of all of the users in your cluster, navigate to the SQL Users page.

On the SQL Users page, you can do the following:

Create a user
Change a user's password
Remove a user

To list all the users in your cluster, use the SHOW USERS statement:

> SHOW USERS;

Change a SQL user's password

Note:

Only users with the Org Administrator, or Cluster Admin can change a user's password. If you do not have the required permissions, ask a user with one of the required roles to change the password.

To change a user's password:

Navigate to the SQL Users page.
In the row of the user whose password needs to be changed, click the ... button.
From the dropdown, select Change Password.
Click Generate & save password.
Copy the generated password and save it in a secure location.

To change a user's password, use the ALTER USER statement:

> ALTER USER <user> WITH PASSWORD '<new password>';

Remove a SQL user

To remove a user:

Navigate to the SQL Users page.
In the row of the user you want to remove, click the ... button.
From the dropdown, select Delete SQL User.
Click Delete.

To remove a user, use the DROP USER statement:

> DROP USER <user>;

Note:

All of a user's privileges must be revoked before the user can be dropped.

Grant privileges to a SQL user

Access to the data in your cluster is controlled by privileges. When a user connects to a database, either via the CockroachDB SQL client or a PostgreSQL driver or ORM, CockroachDB checks the user's privileges for each statement executed. If the user does not have sufficient privileges for a statement, CockroachDB returns an error.

To grant a user privileges for specific databases and tables in your cluster, use the GRANT statement. For example, to assign a user all privileges for all tables in a database:

> GRANT ALL ON DATABASE <database> TO <user>;

To assign a user more limited privileges for one table in a database:

> GRANT SELECT, INSERT ON TABLE <database>.<table> TO <user>;

For more details, see Privileges and GRANT.

View a SQL user's privileges

To show privileges granted to a user, use the SHOW GRANTS statement:

> SHOW GRANTS ON DATABASE <database> FOR <user>;

Revoke a SQL user's privileges

To revoke privileges from a user, use the REVOKE statement:

> REVOKE INSERT ON TABLE <database>.<table> FROM <user>;

Use SQL roles to manage access

Role-based access control lets you simplify how you manage privileges. In essence, a role is a group containing any number of other roles and users as members. You can assign privileges to a role, and all direct and indirect members of the role will inherit the privileges.

Once you have connected to the cluster, you can set up roles:

To create a role, use the CREATE ROLE statement:
```
> CREATE ROLE <role>;
```
To grant privileges to a role, use the GRANT <privilege> statement:
```
> GRANT <privilege> ON DATABASE <database> TO <role>;
```
To add a user (or another role) to a role, use the GRANT <role> statement:
```
> GRANT <role> TO <user or role>;
```
To revoke privileges from a role, use the REVOKE <privilege> statement:
```
> REVOKE INSERT ON TABLE <database>.<table> FROM <role>;
```
To remove a user (or another role) from a role, use the REVOKE <role> statement:
```
> REVOKE <role> FROM <user or role>;
```
To list all roles in your cluster, use the SHOW ROLES statement:
```
> SHOW ROLES;
```
To remove a role, use the DROP ROLE statement:
```
> DROP ROLE <role>;
```
Note:

All of a role's privileges must be revoked before the role can be dropped.

Pricing

Contact us

Sign In

Manage Users, Roles, and Service Accounts

Manage your organizations

Manage an organization's users

Invite team members to an organization

Change a team member's roles

Remove a team member

Revoke a pending invite

Delete an email address

Delete an organization

Manage service accounts

Create a service account

Edit roles on a service account

API access

Create API keys

Delete API keys

Edit API key names

Manage SQL users on a cluster

Create a SQL user

View all SQL users in your cluster

Change a SQL user's password

Remove a SQL user

Grant privileges to a SQL user

View a SQL user's privileges

Revoke a SQL user's privileges

Use SQL roles to manage access

See also