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.

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):

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.

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) and a nonce (replay protection), both verified on callback in 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