Skip to content

feat(auth): enable OIDC SSO for self-hosted instances

jedmund requested to merge jedmund/oidc-pocketid-auth into canary

Created by: jedmund

Summary

  • Unlocks the existing better-auth SSO flow for self-hosted Dokploy via a new env var DOKPLOY_ENABLE_SELF_HOSTED_SSO=true — no license required.
  • Adds DOKPLOY_SSO_PRIMARY=true to make SSO the default sign-in (password form hidden behind an escape-hatch link).
  • All OIDC/SAML scaffolding (schema, registration UI, sign-in flow, callbacks) was already in place — this just bypasses the license gates on the three SSO surfaces (showSignInWithSSO, the ssoRouter endpoints, and the SSO settings page). Other enterprise features (audit logs, whitelabeling, custom roles) remain license-gated.

Why

Dokploy's free self-hosted edition already ships a complete OIDC implementation via @better-auth/sso, but it's hidden behind an enterprise license check. This change lets a home/self-hosted operator with an OIDC provider (e.g. PocketID, Authentik, Keycloak) point Dokploy at it without buying a license.

PocketID setup

  1. Set DOKPLOY_ENABLE_SELF_HOSTED_SSO=true (and optionally DOKPLOY_SSO_PRIMARY=true) on the Dokploy instance.
  2. In PocketID, create an OIDC client with callback URL https://<your-dokploy>/api/auth/sso/callback/<providerId>.
  3. In Dokploy: Settings → SSO → Register OIDC provider — paste issuer (PocketID base URL), client ID, client secret, scopes openid email profile, and the email domains you want auto-routed.

Test plan

  • Regression (no flag): with both env vars unset, /dashboard/settings/sso still shows the "Enterprise SSO" lock card and the login page does not show a "Sign in with SSO" button.
  • Self-hosted unlock: with DOKPLOY_ENABLE_SELF_HOSTED_SSO=true, the SSO settings page renders directly, register-OIDC dialog works, and the login page shows the SSO button.
  • OIDC flow (PocketID): register a provider → log out → enter an email in the configured domain → land on PocketID → redirected back to /dashboard/home with a session.
  • Primary mode: with both flags on, login page opens with the SSO email form expanded and the password form hidden; "Use email and password instead" link reveals the password form.
  • Cloud unchanged: with IS_CLOUD=true and the new flags unset, sign-in shows GitHub/Google/email + SSO as before.

🤖 Generated with Claude Code

Merge request reports