diff --git a/docs/use-cases/observability/clickstack/managing/index.md b/docs/use-cases/observability/clickstack/managing/index.md index c21ab1c9a4a..eddbd459667 100644 --- a/docs/use-cases/observability/clickstack/managing/index.md +++ b/docs/use-cases/observability/clickstack/managing/index.md @@ -20,6 +20,7 @@ This section describes how to manage ClickStack. | [Going to production](/use-cases/observability/clickstack/production) | Recommended steps and best practices before running ClickStack in production. | | [Materialized views](/use-cases/observability/clickstack/materialized_views) | A detailed guide to using materialized views in ClickStack to accelerate query performance. | | [Performance tuning](/use-cases/observability/clickstack/performance_tuning) | A comprehensive guide to tuning ClickStack for large-scale workloads. | +| [RBAC](/use-cases/observability/clickstack/rbac) | Configure role-based access control to manage team permissions for dashboards, saved searches, and sources. | ## Core ClickHouse concepts {#core-concepts} diff --git a/docs/use-cases/observability/clickstack/managing/rbac.md b/docs/use-cases/observability/clickstack/managing/rbac.md new file mode 100644 index 00000000000..6526afcef04 --- /dev/null +++ b/docs/use-cases/observability/clickstack/managing/rbac.md @@ -0,0 +1,191 @@ +--- +slug: /use-cases/observability/clickstack/rbac +title: 'Role-based access control (RBAC)' +sidebar_label: 'Role-based access control' +toc_max_heading_level: 2 +pagination_prev: null +pagination_next: null +description: 'Configure role-based access control in ClickStack to manage team permissions for dashboards, saved searches, sources, alerts, and more.' +doc_type: 'guide' +keywords: ['clickstack', 'rbac', 'roles', 'permissions', 'access control', 'security'] +--- + +import Image from '@theme/IdealImage'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import rbac_section from '@site/static/images/clickstack/rbac/rbac-section.png'; +import add_role_modal from '@site/static/images/clickstack/rbac/add-role-modal.png'; +import dashboard_fine_grained_example from '@site/static/images/clickstack/rbac/dashboard-fine-grained-example.png'; +import security_policies from '@site/static/images/clickstack/rbac/security-policies.png'; +import team_members from '@site/static/images/clickstack/rbac/team-members.png'; +import edit_team_member from '@site/static/images/clickstack/rbac/edit-team-member.png'; +import default_vs_fine_grained from '@site/static/images/clickstack/rbac/default-vs-fine-grained.png'; +import condition_tip from '@site/static/images/clickstack/rbac/condition-tip.png'; +import access_rules_tip from '@site/static/images/clickstack/rbac/access-rules-tip.png'; +import dashboard_id_and_tag_example from '@site/static/images/clickstack/rbac/dashboard-id-and-tag-example.png'; +import team_page_cloud from '@site/static/images/clickstack/rbac/team-page-cloud.png'; +import team_page_hyperdx from '@site/static/images/clickstack/rbac/team-page-hyperdx.png'; + +ClickStack includes role-based access control (RBAC) so you can define custom roles with fine-grained permissions over [dashboards](/use-cases/observability/clickstack/dashboards), [saved searches](/use-cases/observability/clickstack/search), sources, [alerts](/use-cases/observability/clickstack/alerts), webhooks, and notebooks. Permissions work at two levels: resource-level access (no access, read, or manage per resource type) and optional fine-grained rules that restrict access to individual resources by name, tag, or ID. ClickStack ships with three built-in roles, and you can create custom roles to match your team's needs. + +:::note Managed ClickStack only +RBAC is only available in Managed ClickStack deployments. +::: + +## User access prerequisites {#user-access-prerequisites} + +ClickStack authenticates through ClickHouse Cloud. Before you can assign ClickStack roles, each user must: + +1. **Be invited to your ClickHouse Cloud organization.** An organization admin invites users from the Cloud console. See [Manage cloud users](/cloud/security/manage-cloud-users) for details. +2. **Have SQL Console access on the service.** Navigate to your service's **Settings** → **SQL Console Access** and set the appropriate permission level: + +| Cloud SQL Console access | ClickStack access | +|---|---| +| **SQL Console Admin** (Full Access) | Full access to ClickStack. Required for enabling [alerts](/use-cases/observability/clickstack/alerts). | +| **SQL Console Read Only** (Read Only) | Can view observability data and create dashboards. | +| **No access** | Can't access ClickStack. | + +Once a user has Cloud access, they appear in the ClickStack **Team Settings** page where you can assign a ClickStack role. + + + +ClickStack Team Settings page showing team members and their roles + + +ClickHouse Cloud Users and roles page + + + +## Built-in roles {#built-in-roles} + +ClickStack includes three system roles. You can't edit or delete these. The Admin role is assigned to the team creator by default. + +| Permission | Admin | Member | ReadOnly | +|---|:---:|:---:|:---:| +| Read all resources | ✓ | ✓ | ✓ | +| Manage dashboards | ✓ | ✓ | | +| Manage saved searches | ✓ | ✓ | | +| Manage sources | ✓ | ✓ | | +| Manage alerts | ✓ | ✓ | | +| Manage webhooks | ✓ | ✓ | | +| Manage notebooks | ✓ | ✓ | | +| Update team settings | ✓ | ✓ | | +| Create/delete teams | ✓ | | | +| Manage users and invitations | ✓ | | | + +## Assigning roles to team members {#assigning-roles} + +Team members with role assignments + +The **Team Settings** page lists all team members with their current role. To change a role, click **Edit** next to the user's name and select a new role. Each user has exactly one role. + +Edit team member + +### Default new user role {#default-new-user-role} + +You can set a default role for new users under [Security policies](#security-policies). New users who auto-join the team are automatically assigned this role. + +## Creating a custom role {#creating-a-role} + + + +### Navigate to Team Settings {#step-navigate} + +Open **Team Settings** and scroll to **RBAC Roles**. + +RBAC Roles + +### Add a new role {#step-add-role} + +Click **+ Add Role**. Enter a **Role Name** and optionally add a **Description**. + +### Configure permissions and save {#step-configure} + +Set permissions for the role, then click **Create Role**. + +Add Role modal + + + +Custom roles appear alongside system roles in the RBAC Roles section, with **Edit** and **Delete** controls. + +## Role permissions {#role-permissions} + +### Resource permissions {#resource-permissions} + +Each role grants an access level per resource type. The three levels are: + +| Access level | What it allows | +|---|---| +| **No Access** | The resource type is hidden from the role entirely. | +| **Read** | View the resource and its configuration, but not create, edit, or delete it. | +| **Manage** | Full control — create, edit, and delete resources of that type. | + +The resource types you can control are: + +- **[Dashboards](/use-cases/observability/clickstack/dashboards)** — saved dashboard layouts and charts. +- **[Saved searches](/use-cases/observability/clickstack/search)** — persisted log/trace/event queries. +- **Sources** — ingestion source configurations. +- **[Alerts](/use-cases/observability/clickstack/alerts)** — alert rules and their notification settings. +- **Webhooks** — outbound notification destinations (such as Slack, PagerDuty, and generic HTTP endpoints) that [alerts](/use-cases/observability/clickstack/alerts) deliver to. This doesn't refer to the ClickStack API. +- **Notebooks** — collaborative investigation notebooks. + +### Administrative permissions {#administrative-permissions} + +In addition to resource permissions, each role includes two administrative settings: + +- **Users** (No Access · Limited Access) — controls whether the role can view team members and their roles. Only Admins can invite, remove, or update users. +- **Team** (Read · Manage) — controls whether the role can view or modify team-level settings such as security policies and RBAC configuration. + +### Fine-grained access rules {#fine-grained-access-rules} + +Dashboards, Saved Searches, Sources, and Notebooks support fine-grained controls that restrict access to individual resources within a category. Use these when you need to limit a role to specific resources rather than granting blanket access to the entire resource type. + +#### Default access vs. fine-grained controls {#access-control-modes} + +Each resource type has an **Access Control Mode**: + +- **Default Access** — applies a single access level (No Access, Read, or Manage) to all resources of that type. +- **Fine-Grained Controls** — lets you define access rules that match specific resources by condition. Resources that don't match any rule default to no access. + +To switch modes, click the chevron to expand a resource type in the role editor, then toggle the **Access Control Mode**. + +Default Access vs Fine-Grained Controls modes in the role editor + +#### Configuring access rules {#configuring-access-rules} + +Each access rule consists of a **condition** and an **access level**. Conditions match resources by their properties: + +Condition tooltip: match resources by Name or Tag (shown by the title) or by ID (found in the URL) + +| Condition field | Operators | What it matches | Example | +|---|---|---|---| +| **Name** | `is`, `contains` | The display name of the resource — for example, the dashboard title. | Name contains `production` — matches any dashboard with "production" in its title. | +| **Tag** | `is`, `contains` | Tags assigned to the resource via the tag panel in the top-right corner of the resource view. Available for Dashboards, Saved Searches, and Notebooks only. | Tag is `critical` — matches resources tagged "critical." | +| **ID** | `is`, `contains` | The resource identifier, found in the URL bar when you open the resource. | ID is `abc123` — matches a single specific resource. | + +The following screenshot shows both the dashboard ID highlighted in the URL bar and a "TESTING" tag visible in the tag panel (top-right). + +Dashboard showing the resource ID in the URL bar and a tag in the top-right corner + +You can add multiple rules per resource type. Each rule is checked independently using OR logic — a resource is accessible if it matches **any** rule. Resources that don't match any rule aren't accessible. + +Access rules with OR logic tooltip + +**Example**: To give a role read-only access to testing dashboards, expand Dashboards, switch to Fine-Grained Controls, and add two rules: +- **Name** `contains` `testing` with access level **Read** +- **Tag** `is` `testing` with access level **Read** + + A dashboard that matches either rule is accessible. + +Two fine-grained access rules joined by OR: Name contains testing with Read access, and Tag is testing with Read access + +## Security policies {#security-policies} + +The **Security Policies** section in **Team Settings** provides additional controls. + +**Default New User Role** sets the role automatically assigned to new users who join the team. + +**Generative AI** lets you enable or disable LLM-powered features (such as natural language query generation) powered by Anthropic or Amazon Bedrock. When disabled, no data is sent to AI providers. + +Security policies diff --git a/sidebars.js b/sidebars.js index df021f2bd44..d98865396d1 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1974,6 +1974,7 @@ const sidebars = { 'use-cases/observability/clickstack/managing/production', 'use-cases/observability/clickstack/managing/materialized_views', 'use-cases/observability/clickstack/managing/performance_tuning', + 'use-cases/observability/clickstack/managing/rbac', ], }, { diff --git a/static/images/clickstack/rbac/access-rules-tip.png b/static/images/clickstack/rbac/access-rules-tip.png new file mode 100644 index 00000000000..203b09e9765 Binary files /dev/null and b/static/images/clickstack/rbac/access-rules-tip.png differ diff --git a/static/images/clickstack/rbac/access-rules.png b/static/images/clickstack/rbac/access-rules.png new file mode 100644 index 00000000000..8159bab35e2 Binary files /dev/null and b/static/images/clickstack/rbac/access-rules.png differ diff --git a/static/images/clickstack/rbac/add-role-modal.png b/static/images/clickstack/rbac/add-role-modal.png new file mode 100644 index 00000000000..02fab215a80 Binary files /dev/null and b/static/images/clickstack/rbac/add-role-modal.png differ diff --git a/static/images/clickstack/rbac/condition-tip.png b/static/images/clickstack/rbac/condition-tip.png new file mode 100644 index 00000000000..b0ea67dde19 Binary files /dev/null and b/static/images/clickstack/rbac/condition-tip.png differ diff --git a/static/images/clickstack/rbac/dashboard-fine-grained-example.png b/static/images/clickstack/rbac/dashboard-fine-grained-example.png new file mode 100644 index 00000000000..6c880ccc604 Binary files /dev/null and b/static/images/clickstack/rbac/dashboard-fine-grained-example.png differ diff --git a/static/images/clickstack/rbac/dashboard-id-and-tag-example.png b/static/images/clickstack/rbac/dashboard-id-and-tag-example.png new file mode 100644 index 00000000000..1bc39816886 Binary files /dev/null and b/static/images/clickstack/rbac/dashboard-id-and-tag-example.png differ diff --git a/static/images/clickstack/rbac/dashboard-id-example.png b/static/images/clickstack/rbac/dashboard-id-example.png new file mode 100644 index 00000000000..169de36c9de Binary files /dev/null and b/static/images/clickstack/rbac/dashboard-id-example.png differ diff --git a/static/images/clickstack/rbac/data-scopes.png b/static/images/clickstack/rbac/data-scopes.png new file mode 100644 index 00000000000..7b1edb3e14d Binary files /dev/null and b/static/images/clickstack/rbac/data-scopes.png differ diff --git a/static/images/clickstack/rbac/default-vs-fine-grained.png b/static/images/clickstack/rbac/default-vs-fine-grained.png new file mode 100644 index 00000000000..41bceebca59 Binary files /dev/null and b/static/images/clickstack/rbac/default-vs-fine-grained.png differ diff --git a/static/images/clickstack/rbac/edit-team-member.png b/static/images/clickstack/rbac/edit-team-member.png new file mode 100644 index 00000000000..9097acd2527 Binary files /dev/null and b/static/images/clickstack/rbac/edit-team-member.png differ diff --git a/static/images/clickstack/rbac/fine-grained.png b/static/images/clickstack/rbac/fine-grained.png new file mode 100644 index 00000000000..9614439019d Binary files /dev/null and b/static/images/clickstack/rbac/fine-grained.png differ diff --git a/static/images/clickstack/rbac/rbac-section.png b/static/images/clickstack/rbac/rbac-section.png new file mode 100644 index 00000000000..0ed935804ce Binary files /dev/null and b/static/images/clickstack/rbac/rbac-section.png differ diff --git a/static/images/clickstack/rbac/security-policies.png b/static/images/clickstack/rbac/security-policies.png new file mode 100644 index 00000000000..533caa176d9 Binary files /dev/null and b/static/images/clickstack/rbac/security-policies.png differ diff --git a/static/images/clickstack/rbac/team-members.png b/static/images/clickstack/rbac/team-members.png new file mode 100644 index 00000000000..0d08f408404 Binary files /dev/null and b/static/images/clickstack/rbac/team-members.png differ diff --git a/static/images/clickstack/rbac/team-page-cloud.png b/static/images/clickstack/rbac/team-page-cloud.png new file mode 100644 index 00000000000..7d3c5f39681 Binary files /dev/null and b/static/images/clickstack/rbac/team-page-cloud.png differ diff --git a/static/images/clickstack/rbac/team-page-hyperdx.png b/static/images/clickstack/rbac/team-page-hyperdx.png new file mode 100644 index 00000000000..978e4464169 Binary files /dev/null and b/static/images/clickstack/rbac/team-page-hyperdx.png differ