Access control

src/Access/ implements ClickHouse's RBAC: users, roles, grants, row policies, quotas, and settings profiles. The same code backs both XML-configured users (legacy users.xml) and SQL-managed users (CREATE USER ...), and supports multiple persistent backends.

Concepts

• User — an authenticated principal. Has authentication methods, default roles, default database, settings profile, and quotas.
• Role — a named collection of grants. Roles can be granted to users or to other roles.
• Grant — a privilege (SELECT, INSERT, ALTER, DROP, CREATE, SOURCES, dictGet, …) on a database/table/column.
• Row policy — a per-(table, role) WHERE clause automatically appended to queries.
• Settings profile — a bundle of settings that can be inherited by users and roles.
• Quota — limits on queries, errors, rows, bytes, executed time, and result rows over a time window.

Backends

Concrete IAccessStorage implementations:

Storage	File	Notes
UsersConfigAccessStorage	UsersConfigAccessStorage.cpp	Reads users.xml and users.d/. Read-only at runtime.
DiskAccessStorage	DiskAccessStorage.cpp	The default SQL-managed backend. Persists users/roles to local disk under access/.
LDAPAccessStorage	LDAPAccessStorage.cpp	LDAP-backed user lookup.
ReplicatedAccessStorage	ReplicatedAccessStorage.cpp	Stores access entities in Keeper for cluster-wide consistency.
MemoryAccessStorage	MemoryAccessStorage.cpp	In-memory for tests.
MultipleAccessStorage	MultipleAccessStorage.cpp	Composes several backends.

Backends are wired up in Server.cpp from <user_directories>. The composed MultipleAccessStorage is what the rest of the engine talks to.

Authentication

Authentication.cpp and AuthenticationData.cpp enumerate the methods:

• no_password, plaintext_password, sha256_password, double_sha1_password, bcrypt_password.
• kerberos, ldap, ssh_key, jwt.
• http_basic, certificate, external (delegated).

HTTPAuthClient.cpp, Common/SSH/, JWTValidator.cpp, Kerberos.cpp, LDAPClient.cpp provide the underlying clients. The MySQL/PostgreSQL handlers expose the matching wire-protocol auth flows.

Privileges

AccessRights.cpp is the model. A privilege is (access_flag, database, table, column). AccessFlags.cpp enumerates the flags and their hierarchical relationships (SHOW DATABASES is implied by SHOW TABLES on any table in the database, etc.).

AccessControl.cpp is the central facade attached to the Context. Every interpreter calls context->checkAccess(...) before performing privileged operations.

Row policies and quotas

• RowPolicy.cpp — model of a row policy. Multiple policies for the same (table, role) are AND'd together.
• Quota.cpp and QuotaUsage.cpp — quota state tracking. QuotasView.cpp exposes them as a system table.
• EnabledRowPolicies.cpp, EnabledQuota.cpp — per-context evaluation.

Settings profiles

Settings profiles bundle a Settings/MergeTreeSettings snapshot and a constraints map (SettingsConstraints.cpp) that limits how a user can change those settings. Backed by SettingsProfile.cpp.

Default users and the default profile

A fresh ClickHouse install ships with a default user, no password, listening on 127.0.0.1 only. The default profile is default and lives in users.xml. Production deployments override these.

On-disk layout

DiskAccessStorage writes one file per entity under <path>/access/:

access/
├── users/<uuid>.sql
├── roles/<uuid>.sql
├── row_policies/<uuid>.sql
├── settings_profiles/<uuid>.sql
└── quotas/<uuid>.sql

Each file is the CREATE/ATTACH statement for the entity. This makes the access state introspectable and easy to back up.

DDL surface

The SQL surface is defined in src/Parsers/Access/:

• CREATE/ALTER/DROP USER
• CREATE/ALTER/DROP ROLE
• GRANT, REVOKE
• CREATE/ALTER/DROP ROW POLICY
• CREATE/ALTER/DROP QUOTA
• CREATE/ALTER/DROP SETTINGS PROFILE
• SET ROLE, SHOW GRANTS, SHOW CREATE USER, SHOW ACCESS, CHECK GRANT

InterpreterCreate*Query in src/Interpreters/Access/ executes them.

Entry points for modification

• New auth method → extend AuthenticationData and the relevant client under src/Access/.
• New privilege → add to AccessFlags.cpp and call context->checkAccess(...) from the interpreter that requires it.
• New backend → subclass IAccessStorage and register it.

Related pages

• Server — bootstraps AccessControl.
• Server protocols — where authentication runs.
• Configuration — <user_directories>, <users_config>.