Skip to main content

Authentication

ZenSearch ships with three authentication modes for self-hosted deployments. Pick one at install time; switching later requires re-provisioning user accounts but is otherwise straightforward.

ModeUse caseStatus
OIDCSelf-hosted SSO via Keycloak, Auth0, Okta, Azure AD, Google, or any OIDC-compliant provider. The default for production.GA
ClerkManaged identity service. Useful for cloud-style deployments without standing up your own IdP.GA
SAMLEnterprise SSO for IdPs that don't speak OIDC, or where SAML is the corporate standard.Available on Enterprise plans with deployment assistance
NoneSingle shared dev identity. Evaluation only — never expose a none-mode deployment to a network where multiple users can reach it.Dev only
note

OIDC covers the vast majority of modern IdPs — Okta, Azure AD, Auth0, Keycloak, Google Workspace, and every other OIDC-compliant provider. If you're evaluating between SAML and OIDC for a new deployment, we recommend OIDC. SAML integrations are supported on Enterprise plans and typically require light engagement from our team to configure against your specific IdP.

The default Developer Edition install uses None mode for zero-config evaluation. Enable a real provider before sharing the deployment with your team.

OIDC​

OIDC works with any OpenID Connect–compliant provider (Keycloak, Auth0, Okta, Azure AD, Google Workspace, OneLogin, JumpCloud, etc.).

Setup​

  1. In your IdP, register a new application:

    • Application type: Web / SPA depending on your provider's terminology
    • Redirect URI: https://your-zensearch-host/auth/callback
    • Scopes: at minimum openid, profile, email. Add any custom claims you want surfaced (e.g., groups, manager_email).

  2. Copy the issuer URL, client ID, and client secret.

  3. In your ZenSearch .env, set:

    AUTH_MODE=oidc
    OIDC_ISSUER_URL=https://your-idp.example.com/realms/zensearch
    OIDC_CLIENT_ID=zensearch
    OIDC_CLIENT_SECRET=...

  4. Restart ZenSearch.

Provider-specific issuer URLs​

ProviderIssuer URL
Keycloakhttps://keycloak.example.com/realms/<realm>
Auth0https://<tenant>.auth0.com/
Oktahttps://<org>.okta.com/oauth2/default
Google Workspacehttps://accounts.google.com
Azure ADhttps://login.microsoftonline.com/<tenant-id>/v2.0
OneLoginhttps://<subdomain>.onelogin.com/oidc/2

Custom claims​

If your IdP includes additional claims in the ID token, ZenSearch can use them to keep the org chart in sync automatically:

  • manager_email (or manager / reports_to) → reports-to relationship
  • department (or dept)
  • title (or job_title)
  • job_role (or org_role)

Both top-level claims and public_metadata (for Clerk-style claim bags) are read. Empty values don't clobber existing CSV-imported data.

SAML​

SAML is available on Enterprise plans. Configuration varies meaningfully by IdP (metadata discovery, attribute mapping, signed vs unsigned assertions, IdP-initiated vs SP-initiated flow), so SAML rollouts are supported as an engaged process with our team rather than a DIY .env setting.

If SAML is a hard requirement, contact [email protected] — we'll work through IdP metadata, attribute mapping, and test-assertion validation with you. If you're flexible on protocol, OIDC typically gets you to production faster and integrates the same IdPs (Okta, Azure AD, Auth0, OneLogin, JumpCloud, etc.).

Group / role claims on SAML assertions, once attribute mapping is configured, feed the same external RBAC mapping as OIDC groups.

Clerk​

Clerk is a managed identity service that handles user sign-up, social logins, MFA, and session management. Useful when you don't want to operate your own IdP.

Setup​

  1. Create a Clerk application at clerk.com.

  2. Add the ZenSearch domain to the application's allowed origins.

  3. Copy the Frontend API and Secret Key from the Clerk dashboard.

  4. In your ZenSearch .env:

    AUTH_MODE=clerk
    CLERK_DOMAIN=your-app.clerk.accounts.dev
    CLERK_SECRET_KEY=...

  5. Restart ZenSearch.

User identity, claims, and sessions are managed entirely in the Clerk dashboard.

Switching modes​

Changing AUTH_MODE after users are provisioned is supported but requires care:

  • Existing users keep their internal IDs and team memberships.
  • On next sign-in, the new provider must return a matching email claim for ZenSearch to link the existing record.
  • Mismatched emails create new users — you'll then need to migrate their team memberships manually.

For production, pick a mode at install time and stick with it.

None mode (development only)​

AUTH_MODE=none skips all authentication. Every request is treated as the same hardcoded development user. This is convenient for local evaluation but is not safe for any deployment reachable by more than one person.

The platform refuses to start in none mode if ENVIRONMENT=production.