Authentication & Roles

CH-UI has two authentication models depending on how you run it.

Single Sign-On: CH-UI also supports OIDC SSO (Okta, Entra ID, Google, Keycloak, …) alongside password login. See Single Sign-On.

Self-Hosted: ClickHouse Credentials

The self-hosted server authenticates against ClickHouse credentials over the selected connection tunnel.

Login Flow

1. User picks a connection.
2. User provides ClickHouse username/password.
3. CH-UI verifies credentials through tunnel.
4. CH-UI issues chui_session cookie.

Cloud: Magic Link + ClickHouse Credentials

CH-UI Cloud uses a two-layer authentication model:

Console Authentication (Magic Link)

The Console at console.ch-ui.com uses passwordless email authentication:

1. User enters their email address.
2. A magic link is sent to their inbox (via Resend).
3. Clicking the link sets a console_session cookie (30-day expiry).
4. User is redirected to their organization.

No passwords are stored. Rate limits: 10 requests per IP, 3 per email per 15 minutes.

Workspace Authentication (ClickHouse Credentials)

Once inside an org workspace (your-org.ch-ui.com), users authenticate with ClickHouse credentials — identical to self-hosted:

1. User picks a connection.
2. User provides ClickHouse username/password.
3. CH-UI verifies credentials through tunnel.
4. CH-UI issues chui_session cookie.

Session Endpoint

curl http://localhost:3488/api/auth/session \
  -H "Cookie: chui_session=..."

Response includes:

• authenticated
• user (the person's email for SSO sessions, the ClickHouse user otherwise)
• user_role
• via_sso (whether the session was created through SSO)
• active connection info
• app version

The /api/auth/config endpoint (unauthenticated) reports which login methods are available so the login page can render the right options:

curl http://localhost:3488/api/auth/config
# { "password_login": true, "oidc_enabled": true, "oidc_login_url": "/api/auth/oidc/login" }

Role Resolution

CH-UI supports app-level roles, overridable per user by an admin:

Admin-only routes are guarded server-side (RequireAdmin); workspace writes are guarded by RequireWriter (admin or analyst). Data access is always governed by the user's own ClickHouse grants regardless of CH-UI role.

Login Failure Statuses

Common statuses returned by /api/auth/login:

• 401 invalid credentials
• 429 IP/user rate limit
• 503 selected connection offline

Logout

curl -X POST http://localhost:3488/api/auth/logout \
  -H "Cookie: chui_session=..."

This deletes the server session and clears cookie state.

Audit

Both successful and failed logins are written to the immutable audit trail (with user, IP, and timestamp), so brute-force and credential-stuffing attempts are visible. Audit events can be forwarded to your SIEM — see Monitoring & SIEM.

Security Notes

• In production, cookie is Secure when app runs in production mode.
• Set strong APP_SECRET_KEY.
• Keep ALLOWED_ORIGINS strict to your UI origin(s).
• Terminate TLS natively or at a proxy — see Security.