Single Sign-On (SSO)

CH-UI supports OpenID Connect (OIDC) SSO against any compliant identity provider — Okta, Microsoft Entra ID, Google Workspace, Keycloak, Auth0, and others. SSO is a Pro feature.

SSO is configured once, server-wide — via environment variables (or the matching oidc_* keys in server.yaml), or from Admin → SSO in the UI.

How it works

OIDC authenticates the person. CH-UI never receives a ClickHouse password from your IdP, so queries run through a per-connection ClickHouse service account that you configure. The person's identity (email) drives their CH-UI role and is recorded in the audit trail. Password login keeps working alongside SSO.

Person ── OIDC ──▶ CH-UI    (identity, role, audit are per person)
                   CH-UI ── service account ──▶ ClickHouse

Because all SSO users share one ClickHouse service account at the database layer, ClickHouse-native per-user grants do not apply to them — CH-UI's own RBAC (admin / analyst / viewer) is their access control. Grant the service account the least privilege your SSO users need.

1. Register CH-UI with your IdP

Create an OAuth/OIDC application in your IdP and set the redirect URI to:

https://ch-ui.yourcompany.com/api/auth/oidc/callback

Note the issuer URL, client ID, and client secret. To use role mapping, configure the IdP to include a groups claim in the ID token.

2. Configure CH-UI

Set these via environment variables (or the matching oidc_* keys in server.yaml), or fill in the same fields at Admin → SSO:

OIDC_ISSUER_URL=https://accounts.google.com
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_REDIRECT_URL=https://ch-ui.yourcompany.com/api/auth/oidc/callback

# Optional
OIDC_CONNECTION_ID=                  # connection SSO uses (default: embedded connection)
OIDC_ALLOWED_DOMAINS=yourcompany.com # restrict by email domain (comma-separated)
OIDC_GROUPS_CLAIM=groups             # ID-token claim holding group memberships
OIDC_ADMIN_GROUPS=ch-ui-admins       # IdP groups → admin role (comma-separated)
OIDC_ANALYST_GROUPS=data-analysts    # IdP groups → analyst role

On startup the server logs OIDC SSO enabled and a Sign in with SSO button appears on the login page. If discovery fails (IdP unreachable, bad issuer), CH-UI logs the error and starts with SSO disabled rather than refusing to boot.

Admin → SSO UI (v2.6.0+)

Since v2.6.0 you can configure SSO entirely from Admin → SSO (GET/PUT /api/admin/sso) instead of the environment:

• Settings are stored in the CH-UI database, with the client secret encrypted with APP_SECRET_KEY. The secret is never returned by the API — only a has_secret flag; leaving the field blank on save keeps the stored one.
• Saves apply immediately: the OIDC provider is re-initialized in place, no server restart needed. If discovery fails, the config is saved and the response carries a reload_error so you can fix and retry.
• Env/YAML always wins. When OIDC is configured via environment variables or server.yaml, the Admin UI shows that config read-only and PUT is rejected — edit the server config instead.
• The DB config supports two fields with no env equivalent: viewer_groups (IdP groups explicitly mapped to the viewer role — the default for unmatched users anyway) and redirect_base_url (base URL used to build the callback URL, falling back to the server's app URL when empty).

Config changes are recorded in the audit log (sso.config_update), without any secret material.

3. Set the ClickHouse service account

Configure the ClickHouse account that SSO sessions query through, on the target connection (admin only):

curl -X PUT https://ch-ui.yourcompany.com/api/connections/<CONNECTION_ID>/sso-account \
  -H 'Content-Type: application/json' \
  --cookie 'chui_session=<admin session>' \
  -d '{"username": "ch_sso_reader", "password": "..."}'

The password is encrypted at rest with APP_SECRET_KEY. Until a service account is set, SSO logins fail with a clear "service account not configured" message.

Role mapping

Group matching is case-insensitive. A user in both an admin and an analyst group gets admin.

Security

• The login flow uses a state parameter (CSRF protection), a nonce (replay protection), and PKCE (RFC 7636, S256 code challenge) — all verified on callback via short-lived HttpOnly cookies scoped to /api/auth/oidc.
• The ID token's signature and audience are verified against the IdP's JWKS, and the nonce is checked before a session is issued.
• Use OIDC_ALLOWED_DOMAINS to restrict sign-in to your corporate email domain(s).
• The session shows the person's email (via_sso: true in /api/auth/session), while queries authenticate to ClickHouse as the service account.

Endpoints