Skip to main content

Authentication

important

It is your responsibility to properly secure your Dashy instance. Never expose your Dashy instance to the public internet or untrusted users without sufficient authentication and authorization in place.

Built-In Auth​

Dashy includes a built-in username/password login, with optional server-side HTTP Basic Auth. This is the easiest way to get a login page, without needing to spin up any other services. The full guide, covering password hashing, env-var passwords, guest access, user roles, visibility controls and security notes, is in the Built-In Auth guide.

To enable, simply add an array of users under appConfig.auth.users, each with a username (user) and a SHA256 hash of their password (hash).

appConfig:
  disableConfigurationForNonAdmin: true
  auth:
    users:
      - user: alicia
        hash: 5994471ABB01112AFCC18159F6CC74B4F511B99806DA59B3CAF5A9C173CACFC5
        type: admin

Optionally set this env var to enforce this on the server-side too

ENABLE_HTTP_AUTH=true

Keycloak​

Dashy supports Keycloak (v17+) as an authentication provider. See the Keycloak guide for the full deploy and configuration walkthrough.

appConfig:
  disableConfigurationForNonAdmin: true
  auth:
    enableKeycloak: true
    keycloak:
      serverUrl: http://localhost:9100
      realm: dashy
      clientId: dashy
      adminRole: dashy-admin

Header Authentication​

Dashy can defer authentication to a reverse proxy that injects the user's identity in a request header. See the Header Authentication guide.

appConfig:
  auth:
    enableHeaderAuth: true
    users:
      - user: alice
        hash: 0a7b1d4c2e...
        type: admin
    headerAuth:
      userHeader: Remote-User
      proxyWhitelist:
        - 172.18.0.2

OIDC​

Dashy has full support for OIDC based auth, with scoped permissions. See either the generic OIDC docs, or our provider-specific guides:

appConfig:
  disableConfigurationForNonAdmin: true # Hide the config editor from non-admins (recommended)
  enableGuestAccess: false              # Optional: view the dashboard read-only without signing in
  enableServiceWorker: true             # Optional: enables the PWA and offline support
  enableAuthProxyCompat: true           # Recover the PWA after a session expires (needs the service worker)
  auth:
    enableOidc: true                    # Turn OIDC on
    oidc:
      clientId: dashy                    # Client ID from your provider
      endpoint: https://auth.example.com/application/o/dashy/ # The issuer URL, not the .well-known one
      scope: openid profile email groups # Scopes to request (groups for adminGroup, roles for adminRole)
      adminGroup: dashy-admins           # Members of this group are admins
      adminRole: dashy-admin             # Or grant admin by role instead
      enableSilentRenew: true            # Refresh the session in the background before it expires

Zero-Trust Tunnels​

Dashy works well with third-party tunnel based auth, allowing you to access your dashboard remotely.

Alternative Authentication Methods​

These are alternatives to Dashy's built-in auth, Keycloak, and OIDC. Most of them sit in front of Dashy at the network or reverse proxy level, which is generally the better approach for anything internet-facing.

Comparison of Auth Options​

MethodTypeDescriptionComplexitySecurityBest for
No AuthBuilt-inThis is the default state Dashy ships with🟢 Easy🔴 WeakInternal usage
Built-In AuthBuilt-inUsername/password list in your config, optionally enforced server-side🟢 Easy🟠 MediumA quick login screen on a trusted LAN
Header AuthBuilt-inTrusts a username header from a proxy that already did the login🟠 Medium🟠 MediumReusing an existing proxy or forward-auth session
OIDC (generic)OIDCAny OpenID Connect provider, with server-side token checks and admin roles🟠 Medium🟢 StrongStandards-based SSO with any IdP
AuthentikOIDCSelf-hosted IdP with a full admin UI, MFA and group policies🟠 Medium🟢 StrongOne login across many self-hosted apps
AutheliaOIDCLightweight self-hosted IdP, configured from a single YAML file🟠 Medium🟢 StrongSelf-hosters who prefer file-based config
KeycloakOIDCHeavyweight enterprise IdP with realms, roles and social login🔴 Hard🟢 StrongLarger or enterprise deployments
Pocket IDOIDCMinimal passkey-only IdP, a single Go binary🟠 Medium🟢 StrongPasswordless homelab SSO
ZitadelOIDCGo/Postgres IdP with project roles (needs an Action to map groups)🔴 Hard🟢 StrongRole-based access across projects
Cloudflare TunnelTunnelOutbound tunnel to Cloudflare's edge, paired with Access for login🟠 Medium🟢 StrongPublic access with no open ports
Tailscale / HeadscaleTunnelPrivate WireGuard mesh, with optional Funnel for public access🟢 Easy🟢 StrongPrivate remote access between your devices
Reverse Proxy AuthProxyAn auth server (Authelia, Authentik, OAuth2 Proxy) in front via forward-auth🟠 Medium🟢 StrongProtecting many apps behind one proxy
Web Server AuthProxyHTTP basic auth handled by your reverse proxy🟢 Easy🟠 MediumA fast password prompt over HTTPS
Client Certificates (mTLS)ProxyRequire a client TLS certificate to connect, enforced at the proxy🔴 Hard🟢 StrongA small fixed set of trusted devices
IP-Based AccessNetworkAllow only certain source IPs at the web server🟢 Easy🟠 MediumAn extra layer on a static IP or VPN
VPNNetworkKeep Dashy off the internet, reach it over WireGuard, Tailscale or OpenVPN🟠 Medium🟢 StrongPrivate access with zero public exposure
SSO / OAuth ProvidersOIDCCloud IdPs (Auth0, Okta, Google) wired in through Dashy's OIDC🟠 Medium🟢 StrongOffloading identity to a managed provider
Cloud Hosting ProvidersPlatformPlatform-level auth (Cloudflare Access, Netlify, Vercel) outside Dashy🟢 Easy🟢 StrongDashboards hosted on a cloud platform

⬆️ Back to Top