Skip to content

Custom role update #6003

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Blargian merged 4 commits into from
Apr 10, 2026
Merged

Custom role update #6003

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7da2edc
Update procedures and screenshots for custom roles
leticiawebb Apr 10, 2026
74932d0
Remove extra lines
leticiawebb Apr 10, 2026
8340747
Add anchor to heading
leticiawebb Apr 10, 2026
9432bcb
review: minor adjustments for vale warnings
Blargian Apr 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 47 additions & 47 deletions docs/cloud/guides/security/01_cloud_access_management/02_manage-cloud-users.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,92 +8,92 @@ keywords: ['cloud users', 'access management', 'security', 'permissions', 'team
---

import Image from '@theme/IdealImage';
import step_1 from '@site/static/images/cloud/guides/sql_console/org_level_access/1_org_settings.png'
import step_2 from '@site/static/images/cloud/guides/sql_console/org_level_access/2_org_settings.png'
import step_3 from '@site/static/images/cloud/guides/sql_console/org_level_access/3_org_settings.png'
import step_4 from '@site/static/images/cloud/guides/sql_console/org_level_access/4_org_settings.png'
import step_5 from '@site/static/images/cloud/guides/sql_console/org_level_access/5_org_settings.png'
import step_6 from '@site/static/images/cloud/guides/sql_console/org_level_access/6_org_settings.png'
import step_7 from '@site/static/images/cloud/guides/sql_console/org_level_access/7_org_settings.png'
import step_1 from '@site/static/images/cloud/guides/control_plane/1_users_and_roles.png'
import step_2 from '@site/static/images/cloud/guides/control_plane/manage_cloud_users/2_invite_user.png'
import step_3 from '@site/static/images/cloud/guides/control_plane/manage_cloud_users/3_invite_user.png'
import step_4 from '@site/static/images/cloud/guides/control_plane/manage_cloud_users/4_invite_user.png'
import step_5 from '@site/static/images/cloud/guides/control_plane/manage_cloud_users/5_edit_user.png'
import step_6 from '@site/static/images/cloud/guides/control_plane/manage_cloud_users/6_edit_user.png'

import EnterprisePlanFeatureBadge from '@theme/badges/EnterprisePlanFeatureBadge'

This guide is intended for users with the Organization Admin role in ClickHouse Cloud.
This guide is intended for users with the Admin role in ClickHouse Cloud.

## Add users to your organization {#add-users}

### Invite users {#invite-users}

Administrators may invite up to three (3) users at a time and assign organization and service level roles at the time of invitation.
Administrators may invite multiple users at a time and assign one or more roles at the time of invitation.

To invite users:
1. Select the organization name in the lower left corner
2. Click `Users and roles`
3. Select `Invite members` in the upper left corner
4. Enter the email address of up to 3 new users
5. Select the organization and service roles that will be assigned to the users
6. Click `Send invites`
<VerticalStepper headerLevel="h3">

Users will receive an email from which they can join the organization. For more information on accepting invitations, see [Manage my account](/cloud/security/manage-my-account).
### Access organization settings and select Users and roles {#users-and-roles-1}

### Add users via SAML identity provider {#add-users-via-saml}
From the services page, select the name of your organization. Select the `Users and roles` menu item from the popup menu.

<EnterprisePlanFeatureBadge feature="SAML SSO"/>
<Image img={step_1} size="lg"/>

If your organization is configured for [SAML SSO](/cloud/security/saml-setup) follow these steps to add users to your organization.
### Select 'Invite members' in the upper left corner {#invite-members}

1. Add users to your SAML application in your identity provider, the users won't appear in ClickHouse until they have logged in once
2. When the user logs in to ClickHouse Cloud they will automatically be assigned the `Member` role which may only log in and has no other access
3. Follow the instructions in the `Manage user role assignments` below to grant permissions
Click the `Invite members` button in the upper left corner.

### Enforcing SAML-only authentication {#enforce-saml}
<Image img={step_2} size="lg"/>

Once you have at least one SAML user in the organization assigned to the Organization Admin role, remove users with other authentication methods from the organization to enforce SAML only authentication for the organization.
### Enter the email address of new members and assign roles {#add-email-and-roles}

## Manage user role assignments {#manage-role-assignments}
Enter email addresses at the top of the invitation screen. Select one or more roles to assign the users.

Users assigned the Organization Admin role may update permissions for other users at any time.
<Image img={step_3} size="lg"/>

<VerticalStepper headerLevel="h3">
### Click `Send invites` {#send-invites}

Click `Send invites` at the bottom of the screen. Users will receive an email from which they can join the organization. For more information on accepting invitations, see [Manage my account](/cloud/security/manage-my-account).

<Image img={step_4} size="lg"/>

### Access organization settings {#access-organization-settings}
</VerticalStepper>

From the services page, select the name of your organization:
### Add users via SAML identity provider {#add-users-via-saml}

<Image img={step_1} size="md"/>
<EnterprisePlanFeatureBadge feature="SAML SSO"/>

### Access users and roles {#access-users-and-roles}
If your organization is configured for [SAML SSO](/cloud/security/saml-setup), follow these steps to add users to your organization.

Select the `Users and roles` menu item from the popup menu.
1. Add users to your SAML application in your identity provider. The users won't appear in ClickHouse until they have logged in once.
2. When the user logs in to ClickHouse Cloud, they will automatically be assigned the default role selected in your SAML configuration.
3. Follow the instructions in the `Manage user role assignments` below to grant permissions

<Image img={step_2} size="md"/>
### Enforcing SAML-only authentication {#enforce-saml}

### Select the user to update {#select-user-to-update}
Once you have at least one SAML user in the organization assigned to the Admin role, remove users with other authentication methods from the organization to enforce SAML only authentication for the organization.

Select the menu item at the end of the row for the user that you which to modify access for:
## Manage user role assignments {#manage-role-assignments}

<Image img={step_3} size="lg"/>
Users assigned the Admin role may update permissions for other users at any time.

### Select `edit` {#select-edit}
<VerticalStepper headerLevel="h3">

<Image img={step_4} size="lg"/>
### Access organization settings and select Users and roles {#users-and-roles-2}

From the services page, select the name of your organization. Select the `Users and roles` menu item from the popup menu.

<Image img={step_1} size="lg"/>

A tab will display on the right hand side of the page:
### Select the user to update and select Edit {#select-user-to-update}

Select the menu item at the end of the row for the user that you wish to modify access for. Select `edit` from the popup menu.

<Image img={step_5} size="lg"/>

### Update permissions {#update-permissions}

Select the drop-down menu items to adjust console-wide access permissions and which features a user can access from within the ClickHouse console. Refer to [Console roles and permissions](/cloud/security/console-roles) for a listing of roles and associated permissions.

Select the drop-down menu items to adjust the access scope of the service role of the selected user. When selecting `Specific services`, you can control the role of the user per service.
Click in the `Roles` box to expand the menu. Select the check boxes to add or remove roles from the user. Refer to [Console roles and permissions](/cloud/security/console-roles) for a listing of roles and associated permissions.

<Image img={step_6} size="md"/>
<Image img={step_6} size="lg"/>

### Save your changes {#save-changes}

Save your changes with the `Save changes` button at the bottom of the tab:

<Image img={step_7} size="md"/>
Save your changes with the `Save changes` button at the bottom of the tab.

</VerticalStepper>

Expand Down
97 changes: 97 additions & 0 deletions docs/cloud/guides/security/01_cloud_access_management/03_manage-custom-roles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
---
sidebar_label: 'Manage custom roles'
slug: /cloud/guides/security/manage-custom-roles
title: 'Manage custom roles'
description: 'This page describes how administrators can add, modify, and remove custom roles'
doc_type: 'guide'
keywords: ['custom roles', 'security', 'permissions']
---

import Image from '@theme/IdealImage';
import step_1 from '@site/static/images/cloud/guides/control_plane/1_users_and_roles.png'
import step_2 from '@site/static/images/cloud/guides/control_plane/manage_custom_roles/2_custom_role.png'
import step_3 from '@site/static/images/cloud/guides/control_plane/manage_custom_roles/3_custom_role.png'
import step_4 from '@site/static/images/cloud/guides/control_plane/manage_custom_roles/4_custom_role.png'
import step_5 from '@site/static/images/cloud/guides/control_plane/manage_custom_roles/5_custom_role.png'
import step_6 from '@site/static/images/cloud/guides/control_plane/manage_custom_roles/6_custom_role.png'

This guide is intended for users with the Admin role in ClickHouse Cloud.

ClickHouse Cloud customers may select from pre-defined system roles or create custom roles to assign to users. For more information on system roles and their associated permissions, review [Console roles and permissions](/cloud/security/console-roles). This guide provides details for managing custom roles.

## Create custom roles {#create-custom-role}

Custom roles can contain a combination of organization, service, and database permissions. Permissions may be applied to all or a subset of services and databases.

<VerticalStepper headerLevel="h3">

### Access organization settings and select Users and roles {#users-and-roles-1}

From the services page, select the name of your organization. Select the `Users and roles` menu item from the popup menu.

<Image img={step_1} size="lg"/>

### Select the `Roles` tab {#roles-tab}

Select the `Roles` tab from the top middle of the screen.

<Image img={step_2} size="lg"/>

### Select `Create new role` from the upper right {#create-new-role}

Select the `Create new role` button in the upper right of the screen.

<Image img={step_3} size="lg"/>

### Name the role {#name-the-role}

Enter a descriptive role name. This will be the name you will see when assigning roles to users and API keys.

<Image img={step_4} size="md"/>

### Click `Allow` and select permission scope {#scope-permissions}

Click the `Allow` button and select from Organization, Service, and/or Database permissions. For a description of all permissions, see [Console roles and permissions](/cloud/security/console-roles).

:::tip
Ensure users who will log into the console have a minimum of Organization > Access organization permissions.
:::

<Image img={step_5} size="md"/>

### Review your new role {#review-role}

Review permissions assigned to your new role before finalizing. Click `Create role` when done.

<Image img={step_6} size="md"/>

</VerticalStepper>

## Update custom roles {#update-custom-role}

Custom roles may be updated after they're created. Users will lose any permissions removed from the role and will gain any permissions added.

:::tip
User permissions are additive. If a user has permission to perform an operation as part of multiple roles, they may not immediately lose access if permission is removed from only one role.
:::

1. Access organization settings and select `Users and roles`
2. Select the `Roles` tab
3. Select the three dots next to the role you would like to update
4. Select `Edit`
5. Modify the permissions
6. Select `Edit role`

## Delete custom roles {#delete-custom-role}

Custom roles may be deleted at any time.

:::warning
You must have at least one user in the organization with administrative permissions. If deleting the role removes administrative permissions from the last user, you can't delete it. To resolve this, assign at least one user the Admin system role before deleting the custom role.
:::

1. Access organization settings and select `Users and roles`
2. Select the `Roles` tab
3. Select the three dots next to the role you would like to delete
4. Review the users and API keys that will lose access when the role is removed. Adjust assignments as needed.
5. Select `Delete role` to complete the process
4 changes: 4 additions & 0 deletions ...s/security/01_cloud_access_management/03_manage-sql-console-role-assignments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,10 @@ import step_5 from '@site/static/images/cloud/guides/sql_console/service_level_a
import step_6 from '@site/static/images/cloud/guides/sql_console/service_level_access/6_service_settings.png'
import step_7 from '@site/static/images/cloud/guides/sql_console/service_level_access/7_service_settings.png'

:::warning
This setting is deprecated and has been replaced with a new setting on the role creation screen in organizations that have migrated to custom roles. For more information, see [Manage cloud users](/cloud/security/manage-cloud-users).
:::

# Configuring SQL console role assignments

> This guide shows you how to configure SQL console role assignments, which
Expand Down
10 changes: 1 addition & 9 deletions docs/cloud/guides/security/01_cloud_access_management/04_saml-sso-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,15 +87,7 @@

### Update default role and session timeout {#update-defaults}

Once the SAML setup is complete, you can set the default role all users will be assigned when they log in and also adjust session timeout settings.

Available default roles include:
- Admin
- Service Admin
- Service Read Only
- Member

For more information regarding permissions assigned to these roles, please review [Console roles and permissions](/cloud/security/console-roles).
Once the SAML setup is complete, you can set the default role(s) all users will be assigned when they log in and also adjust session timeout settings. For a list of available system roles that may be assigned, please review [Console roles and permissions](/cloud/security/console-roles).

Check notice on line 90 in docs/cloud/guides/security/01_cloud_access_management/04_saml-sso-setup.md

View workflow job for this annotation

GitHub Actions / vale

ClickHouse.Wordy 

Suggestion: Use 'please' only if we've inconvenienced the user.

Check warning on line 90 in docs/cloud/guides/security/01_cloud_access_management/04_saml-sso-setup.md

View workflow job for this annotation

GitHub Actions / vale

ClickHouse.BadPlurals 

Rewrite '(s)' to be plural without parentheses.

### Configure your admin user {#configure-your-admin-user}

Expand Down
1 change: 1 addition & 0 deletions docs/cloud/guides/security/01_cloud_access_management/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ This section contains detailed guides for managing access in ClickHouse Cloud
|--------------------------------------------------------|-------------------------------------------------------|
| [Manage my account](/cloud/security/manage-my-account) | Describes how to manage your own user account, including passwords, MFA and account recovery |
| [Manage cloud users](/cloud/security/manage-cloud-users) | An administrator's guide to managing user access in the ClickHouse Cloud console |
| [Manage custom roles](/cloud/guides/security/manage-custom-roles) | An administrator's guide to creating and managing custom roles |
| [Manage SQL console role assignments](/cloud/guides/sql-console/manage-sql-console-role-assignments) | An administrator's guide to managing SQL console users |
| [Manage database users](/cloud/security/manage-database-users) | An administrator's guide to managing database users |
| [SAML SSO setup](/cloud/security/saml-setup) | An administrator's guide to configuring and troubleshooting SAML integrations |
Expand Down
Binary file added static/images/cloud/guides/control_plane/1_users_and_roles.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/cloud/guides/control_plane/manage_cloud_users/2_invite_user.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/cloud/guides/control_plane/manage_cloud_users/3_invite_user.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/cloud/guides/control_plane/manage_cloud_users/4_invite_user.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/cloud/guides/control_plane/manage_cloud_users/5_edit_user.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/cloud/guides/control_plane/manage_cloud_users/6_edit_user.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/cloud/guides/control_plane/manage_custom_roles/2_custom_role.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/cloud/guides/control_plane/manage_custom_roles/3_custom_role.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/cloud/guides/control_plane/manage_custom_roles/4_custom_role.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/cloud/guides/control_plane/manage_custom_roles/5_custom_role.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/cloud/guides/control_plane/manage_custom_roles/6_custom_role.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading