# Security

> Audit user sessions, login attempts, access control roles, and user definitions.

| | |
|---|---|
| **Routes** | `/users`, `/roles`, `/security/sessions`, `/security/login-attempts`, `/security/audit-log` |
| **Feature id** | `security` |
| **Default access** | `public` |
| **Requires auth** | No (set `CHM_FEATURE_SECURITY_ACCESS=authenticated` to gate) |
| **System tables** | `system.users`, `system.roles`, `system.session_log` |
| **ClickHouse grants** | `SELECT` on `system.users`, `system.roles`, `system.session_log`; or `SHOW ACCESS` |

## What it does

The Security section gives operators visibility into who has access to ClickHouse and what they have been doing.

**Users** lists defined ClickHouse users with their authentication methods and profile settings, sourced from `system.users`.

**Roles** lists defined roles, sourced from `system.roles`.

**Sessions** shows user session history with authentication details, sourced from `system.session_log`.

**Login Attempts** shows authentication events with failure reasons, also from `system.session_log`. Use it to detect brute-force attempts or misconfigured client credentials.

**Audit Log** is a filtered view of `system.session_log` focused on security-relevant events.

## Pages

| Page | Route | What it shows | System tables |
|---|---|---|---|
| Users | `/users` | Defined users, auth methods, profiles | `system.users` |
| Roles | `/roles` | Defined roles | `system.roles` |
| Sessions | `/security/sessions` | User session history | `system.session_log` |
| Login Attempts | `/security/login-attempts` | Auth events and failure reasons | `system.session_log` |
| Audit Log | `/security/audit-log` | Security-relevant session events | `system.session_log` |

## Permissions & access

All Security pages share the `security` feature id.

This section contains sensitive access-control data. It is recommended to gate it behind authentication in production:

```bash
CHM_FEATURE_SECURITY_ACCESS=authenticated
```

Disable entirely:

```bash
CHM_FEATURE_SECURITY_ENABLED=false
```

Config file:

```toml
[features.security]
enabled = true
access = "authenticated"
```

## Configuration

No feature-specific configuration. Visibility of data depends on the ClickHouse grants held by the `CLICKHOUSE_USER` chmonitor connects as.

The minimum grant set needed for this section:

```sql
GRANT SELECT ON system.users TO chmonitor_user;
GRANT SELECT ON system.roles TO chmonitor_user;
GRANT SELECT ON system.session_log TO chmonitor_user;
```

Alternatively, `SHOW ACCESS` grants read access to all access-related system tables at once.

## Notes & limitations

- `system.users` and `system.roles` reflect users and roles defined in the ClickHouse access control system. Users defined only in `users.xml` may not appear (depends on ClickHouse version and configuration).
- `system.session_log` must be enabled in the ClickHouse server config (`<session_log>`). If absent, Sessions, Login Attempts, and Audit Log pages show no data.
- Session log retention depends on the `TTL` configured on `system.session_log` (default 30 days).
- Grants (row-level grant assignments) are not yet surfaced as a dedicated page. Use the Users or Roles pages and the ClickHouse `SHOW GRANTS` command directly for grant details.

## Related

- [Authentication](/authentication)
- [Feature permissions](/advanced/feature-permissions)
- [ClickHouse system.session_log docs](https://clickhouse.com/docs/en/operations/system-tables/session_log)