> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Hosted SSO (OIDC)

> Configure OIDC single sign-on for self-hosted ZeroPath deployments, with a Keycloak walkthrough

## Overview

Self-hosted (on-premises) ZeroPath deployments authenticate users locally — there is no dependency on ZeroPath's cloud. The built-in authentication provider supports two methods, which can be enabled together or individually:

* **OIDC single sign-on** against your identity provider
* **Local email/password accounts**, gated by an email-domain allowlist

Any OIDC-compliant identity provider works (Keycloak, Okta, Microsoft Entra ID, PingIdentity, ...). This page uses Keycloak as the worked example because it is the most common self-hosted IdP.

<Info>
  This page applies to self-hosted deployments only. For ZeroPath's cloud product, SSO is configured through the self-service admin portal — see [Enterprise SSO & Directory Sync](/docs/authentication/enterprise-sso).
</Info>

## How it works

Your deployment's Helm values configure a single OIDC provider. At sign-in, users are redirected to your IdP, and on return ZeroPath verifies the identity server-side and provisions the user into your organization:

* The user's email domain must be in your configured domain allowlist.
* The IdP must assert the email as **verified** (`email_verified` claim); unverified emails are rejected.
* Users listed in your configured admin emails receive the admin role on first sign-in; everyone else joins as a member.

## Configuring with Keycloak

<Steps>
  <Step title="Create the OIDC client in Keycloak">
    In your realm, create a confidential OpenID Connect client (client authentication on, standard flow enabled) with the valid redirect URI:

    ```
    https://<your-zeropath-host>/api/auth/sso/callback/<providerId>
    ```

    `<providerId>` is a stable identifier you choose (for example `keycloak`) and reference in the Helm values. Copy the client secret from the client's Credentials tab.
  </Step>

  <Step title="Set the Helm values">
    In your `values.customer.yaml`:

    ```yaml theme={null}
    auth:
      provider: better-auth
      betterAuth:
        sso:
          enabled: true
          providerId: "keycloak"
          protocol: oidc
          domain: "example.com"
          oidc:
            issuer: "https://<keycloak-host>/realms/<realm>"
            clientId: "zeropath-app"
            clientSecret: "<keycloak-client-secret>"
            scopes: [openid, email, profile]
            pkce: true
    ```

    The discovery endpoint is derived from the issuer automatically. The issuer must be HTTPS and reachable from inside your cluster, because ZeroPath performs the token exchange server-side.
  </Step>

  <Step title="Trust private certificates (if applicable)">
    If your IdP uses a certificate from an internal CA, provide a complete PEM trust bundle (public roots plus your CA) through the chart's `caBundleSecret` value.
  </Step>

  <Step title="Upgrade and verify">
    Run your usual `helm upgrade`, then open the login page — it now offers SSO sign-in. Sign in with a test user whose email domain is allowed and whose email is verified in the IdP.
  </Step>
</Steps>

<Info>
  Rotating the OIDC client secret updates a Kubernetes Secret without changing the pod spec, so pods do not restart on their own. After changing `sso.oidc.clientSecret`, restart the frontend deployment (`kubectl rollout restart`) to pick up the new value.
</Info>

## Reference

The complete self-hosted configuration reference — including mixed SSO plus email/password mode, domain allowlist semantics, and troubleshooting — ships with your release package: see `zeropath-on-premises-deployment-guide.md` and the `keycloak-oidc-sso.md` guide in the distribution repository. Your ZeroPath contact can provide the latest versions.