Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

16.2 KB
Raw Blame

πŸ›‘οΈ Proxy Authentication

Authenticate users via your existing reverse proxy (Authentik, Authelia, Cloudflare Zero Trust, etc.).

πŸš€ Quick Start

Proxy authentication delegates identity to your existing authenticating proxy; a shared header is not an identity-provider login. Complete the header trust boundary before enabling it. Keep the existing administrator recovery path until the new login and access checks pass.

  1. Decide who is an administrator. Leaving PROXY_AUTH_ROLE_HEADER unset makes every proxy-authenticated user an administrator. For mixed-access users, configure a role header and the exact intended IdP admin group before enabling proxy login. Do not remove role gating to resolve a denial.

  2. Prepare private configuration. Generate a strong unique shared secret using your trusted secret-management tool. Store it in Pulse and the proxy's private deployment configuration, not command arguments, shared Compose files or a repository. For example, these are mappings, not working defaults:

    PROXY_AUTH_SECRET=<unique-private-shared-secret>
    PROXY_AUTH_USER_HEADER=X-Authentik-Username
    PROXY_AUTH_ROLE_HEADER=X-Authentik-Groups
    PROXY_AUTH_ROLE_SEPARATOR=|
    PROXY_AUTH_ADMIN_ROLE=<exact-idp-admin-group>
    

    Match the header names and separator to what your existing authenticator actually emits. The | example is not correct for an IdP that emits comma-separated groups. Never use the placeholder strings as credentials or invent an admin group to make a user pass.

  3. Complete the proxy boundary. Require successful IdP authentication before forwarding to Pulse. Replace client-supplied identity, role and secret headers with trusted values; deny access if the authenticator is unavailable. A headers-only middleware does not authenticate anyone. Restrict the backend to the existing private proxy path, including any alternate published port.

  4. Verify through the normal browser path. Check an intended administrator, an authenticated non-admin and a signed-out session separately. Signing in does not prove the intended privilege; a non-admin must not gain settings write access. A signed-out session must be challenged or refused by the authenticating proxy, not admitted as a Pulse user. Use existing test accounts and read-only observations, not settings changes or a new public backend.

Apply deployment changes during a suitable maintenance window, preserving the current image, data, credentials and unrelated settings. A Docker environment change needs recreation/redeployment; a restart alone does not apply it. Follow environment precedence.

βš™οΈ Configuration

Variable Description Default
PROXY_AUTH_SECRET Required. Shared secret to verify requests. -
PROXY_AUTH_USER_HEADER Required. Header containing the username. -
PROXY_AUTH_ROLE_HEADER Header containing user groups/roles. -
PROXY_AUTH_ROLE_SEPARATOR Separator for multiple roles in the header. |
PROXY_AUTH_ADMIN_ROLE Role name that grants admin access. admin
PROXY_AUTH_LOGOUT_URL Browser destination for Sign out; use your authenticating proxy's documented logout route. A redirect alone does not prove session revocation. -

Setting PROXY_AUTH_ROLE_HEADER turns on role gating. From then on admin access fails closed unless the role header is present and contains the admin role β€” PROXY_AUTH_ADMIN_ROLE if you set it, otherwise the admin default. A missing or blank role header still authenticates the user, but the user is treated as non-admin.

If you intentionally want every proxy-authenticated user to be an admin, leave PROXY_AUTH_ROLE_HEADER unset and protect Pulse entirely at the proxy/IdP layer.

Running Pulse 5.x? Role gating behaves differently there and needs two extra steps β€” see Pulse 5.x (end-of-life).

⚠ Header Trust Boundary

Pulse trusts these headers completely β€” they are the identity and the privilege decision. Two deployment requirements make that safe, and both are yours to enforce:

  1. Your proxy must replace these headers, never append to them. On every request the proxy has to discard any client-supplied copy of X-Proxy-Secret, your user header, and your role header, then set its own. Pulse reads the first value of a repeated header, so a client-supplied X-Proxy-Roles: admin that arrives ahead of your proxy's value wins β€” and because the proxy supplies the shared secret itself, the client never needs to know it. Replacing only the secret is insufficient: the username and configured role header must also come from the successful authenticator, never from the client. Validate this at the proxy; a direct Pulse probe cannot prove it.
  2. Pulse must not be reachable except through the proxy. Anyone who can connect directly and knows PROXY_AUTH_SECRET can assert any username and any role. Bind Pulse to the proxy's network or to localhost.

Neither of these can be enforced from inside Pulse: a forged header and a genuine one are indistinguishable once they arrive.

πŸ“¦ Examples

These are integration requirements for an already configured authenticator, not complete provider deployment recipes. Follow your installed provider's version-specific documentation for its authentication middleware and trusted identity output. Keep its existing access policy and backend isolation; adding X-Proxy-Secret alone is not a secure setup.

Authentik (with Traefik)

The Pulse router must use the existing Authentik authentication middleware before trusted identity reaches Pulse. Map the authenticated username and groups to the same headers configured in Pulse, with the actual group separator. Strip inbound copies before authentication and replace them with the trusted result. A Traefik headers.customRequestHeaders entry that sets only X-Proxy-Secret does not configure Authentik, protect the route or sanitise the user/group headers. Do not add a static username or admin group as a shortcut.

Authelia (Nginx)

Use the existing Authelia authorisation subrequest and explicitly capture its successful identity and group response for the upstream request. Merely adding auth_request and referencing $upstream_http_remote_user is not a complete identity mapping: the authenticated subrequest's output must be assigned with auth_request_set and used for the headers sent to Pulse. Replace all configured identity, role and secret headers; a failed or unavailable subrequest must not forward an authenticated request. Match Pulse's role separator to the actual Authelia group output, not the example separator above.

Cloudflare Tunnel

A tunnel is a transport, not an Access policy. Require the existing Cloudflare Access application and its authenticated identity on every route to Pulse; protect alternate hostnames and keep direct backend access private. Pulse's proxy authentication does not validate a Cloudflare Access JWT: it checks the shared secret and configured identity/role headers. The trusted Access/connector path must establish identity and replace those headers before forwarding. Do not assume a client-supplied Cf-Access-Authenticated-User-Email or a static secret header proves a login. If no trusted role mapping is available, do not silently fall back to all-users-admin access.

πŸ”§ Troubleshooting

Issue Check
401 Unauthorized Verify X-Proxy-Secret matches PROXY_AUTH_SECRET. Check if headers are being stripped by intermediate proxies.
Not Admin Check the role header actually reaches Pulse and contains the admin role exactly β€” matching is case-sensitive and compares whole roles, so Admins and authentik Admins do not match the admin default. Set PROXY_AUTH_ADMIN_ROLE to your IdP's admin group name. Pulse logs a warning at startup when it falls back to the default.
Sign out returns to the same user Distinguish the browser redirect, proxy session and IdP session; a configured URL is not proof that access ended.

Sign out and session boundaries

Proxy authentication is checked on each request. If the authenticating proxy still supplies a valid identity, Pulse can admit that user again without a local password prompt.

  • With PROXY_AUTH_LOGOUT_URL: Pulse's Sign out action first calls Pulse's local /api/logout endpoint. Only after Pulse confirms success and clears this browser's saved authentication does it send the browser to that URL. A refused request, lost response or browser-cleanup error is shown instead of a redirect; it does not confirm withdrawn access. The destination must perform the required logout in your existing proxy/IdP integration; simply opening a login page or returning to Pulse does not end either upstream session. Some integrations have separate proxy and IdP sessions, so an active IdP session can sign the user straight back in.
  • Without that URL: Pulse uses the same confirmed local logout and browser cleanup, returns to its login page and leaves the proxy/IdP sessions alone. Ending one Pulse browser session does not revoke other browser sessions, API tokens or the shared proxy secret.

Use the logout route documented for your installed authenticating proxy and its application, not an assumed generic IdP URL. Keep any return destination fixed and trusted. The logout URL is exposed to the browser and can appear in startup logs: never put a token, password, session cookie or shared secret in it. Preserve role gating, the private backend and an independent administrator recovery path; do not disable authentication to repair sign-out behaviour.

Check the result through the normal authenticated browser path using a suitable test account, not your only administrator session. On the next ordinary visit to a protected Pulse view, distinguish a proxy challenge from automatic IdP sign-in or continued access as the same user. A redirect, a public /api/health response or an unavailable page is not proof of withdrawn access. A logout error or lost response leaves the result uncertain; clearing browser storage does not establish server-side revocation.

For urgent access withdrawal, use the existing proxy/IdP administrator controls for the affected account and sessions; handle any exposed Pulse API token or proxy secret separately. Do not repeatedly sign out or change permissions just to obtain evidence. A report needs only the Pulse version, which sign-out path was used and the observed challenge, automatic sign-in or error. Keep provider URLs, identity details, cookies and full browser/network exports private.

Verify Headers

First use a normal signed-in browser through your proxy. Check that the intended user has the expected access; do not extract its cookies or use Copy as cURL. The shared proxy secret can assert any identity, so a direct test belongs only on a trusted backend/proxy host or inside its private network. Do not expose the backend port or change firewall rules to make this test possible.

If an authorised administrator needs to isolate Pulse's role check, prepare a temporary private header file in an editor. In that editor, enter the following, substituting your configured user/role header names, real shared secret and a test user's non-admin role (not the admin role). Do not add an API token or session cookie: those would test a different credential path.

X-Proxy-Secret: <your-real-shared-secret>
X-Authentik-Username: testuser
X-Proxy-Roles: none

Run this read-only probe (curl 7.76 or later). It sends no settings changes and prints only the HTTP status, not settings, cookies or credential-bearing logs:

(
  set -eu
  umask 077
  probe_dir=$(mktemp -d)
  header_file="$probe_dir/proxy-headers"
  trap 'test ! -e "$header_file" || rm -- "$header_file"; rmdir -- "$probe_dir"' EXIT
  touch "$header_file"
  vi "$header_file"
  if status=$(curl --disable --silent --show-error --output /dev/null \
    --proto '=http' --noproxy 127.0.0.1 \
    --connect-timeout 5 --max-time 10 \
    --write-out '%{http_code}' --header "@$header_file" \
    http://127.0.0.1:7655/api/system/settings); then
    printf 'HTTP %s\n' "$status"
  else
    curl_exit=$?
    printf 'Proxy probe unavailable (curl exit %s); no role result. Stop here.\n' "$curl_exit" >&2
    exit "$curl_exit"
  fi
)

The probe permits five seconds to connect and ten seconds in total, with no retry. A failed or timed-out transport prints no HTTP role result; retain the error and stop, rather than removing the deadline or repeating the request. The temporary header file is removed on exit, including an editor or curl failure. Cleanup does not revoke the shared secret.

The loopback address applies only on the Pulse host with a loopback listener. --noproxy 127.0.0.1 explicitly bypasses proxy environment settings for this direct request. --disable ignores curl's configuration file, not those environment settings: without the bypass, a proxy could receive the shared secret and its response could be mistaken for Pulse's role result.

Otherwise use the existing private backend address over HTTPS with certificate verification enabled. Replace --proto '=http' with --proto '=https' and the --noproxy value with that exact backend hostname or IP; do not send the shared secret through an environment proxy. Keep backend isolation intact. Do not send forged test identities through a public proxy that should replace them. Keep --disable first to ignore local curl defaults; do not enable verbose/trace output, --insecure or redirect following.

With role gating configured on Pulse 6.2.2 or later, expect 403 for a valid non-admin identity. Repeat the same read-only probe with the role line omitted, then blank: both should still be 403. 200 means admin access is allowed; check whether role gating is configured. 401 means authentication failed, not that the non-admin role was checked. A redirect, connection/TLS error or HTTP 000 is not a successful denial test. Curl deliberately does not fail on 403 here because it is the expected result; assess the printed status separately from transport success. Stop on an unexpected result rather than granting more access. This tests Pulse's direct header handling, not your proxy's header replacement or end-to-end access boundary. Share only the status and redacted configuration names, never the header file or secret.

Pulse 5.x (end-of-life)

The 5.x line is end-of-life and does not receive fixes. Upgrade to 6.2.2 or later, which is where proxy-auth role gating behaves as documented above.

If you cannot upgrade immediately, 5.x needs two configuration changes before role gating actually restricts anyone. Both are required β€” either one alone leaves administrator access open:

  1. Set PROXY_AUTH_ADMIN_ROLE explicitly. 5.x never applies the documented admin default. While it is empty, 5.x skips role checking altogether and treats every proxy-authenticated user as an administrator, whatever their role header says.
  2. Send a non-empty role header on every authenticated request. 5.x only evaluates roles when that header carries a value; an absent or empty header leaves the user an administrator. A user with no groups in your identity provider commonly produces exactly that, so have the proxy send a placeholder such as none rather than nothing. Any non-empty value that does not contain your admin role correctly resolves to non-admin.

Use the private-file probe above with a non-empty non-admin role: it should return 403. A direct 5.x request with the role header omitted can still return 200 despite the explicit admin role; that is the old behaviour, not proof that the workaround failed. The mitigation depends on the real proxy always supplying a non-empty role, including for users with no groups. Verify that end-to-end with such a user; do not expose or bypass the proxy to rely on this workaround. A successful direct test alone does not establish that every proxied request carries the role. Upgrade rather than treating the workaround as equivalent to the current fail-closed behaviour.

6.2.2 and later fix both behaviors: role gating activates on the presence of the role header alone, and an absent or blank header resolves to non-admin.