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:

1. Log in to the console at https://cockroachlabs.cloud/ or your organization's custom domain.
2. 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:

1. 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.
2. On the Access Management page, under the Members tab, click Invite.
3. 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 accepts the invitation, an Org Administrator can grant them additional roles.
4. 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 role

1. On the Access Management page, locate the team member's details whose role you want to change. Note that the Role column lists current organization roles granted to each user. See: Organization User Roles
2. In the row for the target member, click the three-dots Action button and select Edit Roles.

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

   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.

Remove a team member

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

Revoke a pending invite

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

Delete an email address

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

Delete an organization

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

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

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

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

Edit roles on a service account

1. On the Access Management page, select the Service Accounts tab.
2. In the row for the target service account, click, click the three-dots Action button and select Edit Roles.

3. 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:

1. On the Access Management page, select the Service Accounts tab.
2. Click the service account for which you want to create an API key to bring up the Service Account Details page.
3. Click Create API Key.
4. 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.

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

6. Click Done.

Delete API keys

To delete an API key associated with a service account:

1. On the Access Management page, select the Service Accounts tab.
2. Click the service account for which you want to create an API key to bring up the Service Account Details page.
3. Click the Action button for the API key ID in the API Access table.
4. Select Delete.
5. 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:

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

Manage SQL users on a cluster

• View all SQL users in your cluster
• Change a SQL user's password
• Remove a SQL user

Create a SQL user

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

View all SQL users in your cluster

> SHOW USERS;

Change a SQL user's password

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

Remove a SQL user

> DROP USER <user>;

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.

See also

• Client Connection Parameters
• Connect to Your CockroachDB Dedicated Cluster

Was this helpful?