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.

Make proxy authentication setup role-aware and its probe bounded

pulse-triage[bot]7b03e5a10fa7
diff --git a/docs/PROXY_AUTH.md b/docs/PROXY_AUTH.md
index d29887a3f6..d2faaa9c86 100644
--- a/docs/PROXY_AUTH.md
+++ b/docs/PROXY_AUTH.md
@@ -4,14 +4,48 @@ Authenticate users via your existing reverse proxy (Authentik, Authelia, Cloudfl
## πŸš€ Quick Start
-1. **Generate Secret**: Create a strong random string.
-2. **Configure Pulse**: Set these in your deployment's private configuration,
- not a shell command, shared Compose file or repository:
- ```dotenv
- PROXY_AUTH_SECRET=your-random-secret
- PROXY_AUTH_USER_HEADER=X-Authentik-Username
- ```
-3. **Configure Proxy**: Set the proxy to send `X-Proxy-Secret` and the user header.
+Proxy authentication delegates identity to your **existing authenticating proxy**;
+a shared header is not an identity-provider login. Complete the
+[header trust boundary](#-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:
+
+ ```dotenv
+ 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.md#common-overrides-environment-variables).
## βš™οΈ Configuration
@@ -34,49 +68,51 @@ Running Pulse 5.x? Role gating behaves differently there and needs two extra ste
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. The examples below use nginx `proxy_set_header` and Traefik `customRequestHeaders`, which replace; be careful with anything that adds a header rather than setting it.
+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
-The secret values below are placeholders, not defaults. Replace them with the
-same strong unique secret in Pulse and the proxy, using private configuration
-files or your deployment's secret mechanism. Keep the rendered configuration
-and container environment private too; do not share `docker inspect` or
-resolved Compose output.
+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)
-**docker-compose.yml**:
-```yaml
-environment:
- - PROXY_AUTH_SECRET=secure-secret
- - PROXY_AUTH_USER_HEADER=X-Authentik-Username
-```
-**Traefik Middleware**:
-```yaml
-headers:
- customRequestHeaders:
- X-Proxy-Secret: "secure-secret"
-```
+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)
-```nginx
-location / {
- auth_request /authelia;
- proxy_set_header X-Proxy-Secret "secure-secret";
- proxy_set_header Remote-User $upstream_http_remote_user;
- proxy_pass http://pulse:7655;
-}
-```
+
+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
-1. **Zero Trust Dashboard**: Applications β†’ Add Application.
-2. **Settings**: HTTP Settings β†’ HTTP Headers.
-3. **Add Header**: `X-Proxy-Secret` = `your-secret`.
-4. **Pulse Config**: `PROXY_AUTH_USER_HEADER=Cf-Access-Authenticated-User-Email`.
+
+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
@@ -117,12 +153,25 @@ prints only the HTTP status, not settings, cookies or credential-bearing logs:
trap 'test ! -e "$header_file" || rm -- "$header_file"; rmdir -- "$probe_dir"' EXIT
touch "$header_file"
vi "$header_file"
- curl --disable --silent --show-error --output /dev/null \
- --write-out 'HTTP %{http_code}\n' --header "@$header_file" \
- http://127.0.0.1:7655/api/system/settings
+ if status=$(curl --disable --silent --show-error --output /dev/null \
+ --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.
Otherwise use its existing private backend address over HTTPS with certificate
verification enabled. Do not send forged test identities through a public proxy
diff --git a/frontend-modern/public/docs/PROXY_AUTH.md b/frontend-modern/public/docs/PROXY_AUTH.md
index d29887a3f6..d2faaa9c86 100644
--- a/frontend-modern/public/docs/PROXY_AUTH.md
+++ b/frontend-modern/public/docs/PROXY_AUTH.md
@@ -4,14 +4,48 @@ Authenticate users via your existing reverse proxy (Authentik, Authelia, Cloudfl
## πŸš€ Quick Start
-1. **Generate Secret**: Create a strong random string.
-2. **Configure Pulse**: Set these in your deployment's private configuration,
- not a shell command, shared Compose file or repository:
- ```dotenv
- PROXY_AUTH_SECRET=your-random-secret
- PROXY_AUTH_USER_HEADER=X-Authentik-Username
- ```
-3. **Configure Proxy**: Set the proxy to send `X-Proxy-Secret` and the user header.
+Proxy authentication delegates identity to your **existing authenticating proxy**;
+a shared header is not an identity-provider login. Complete the
+[header trust boundary](#-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:
+
+ ```dotenv
+ 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.md#common-overrides-environment-variables).
## βš™οΈ Configuration
@@ -34,49 +68,51 @@ Running Pulse 5.x? Role gating behaves differently there and needs two extra ste
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. The examples below use nginx `proxy_set_header` and Traefik `customRequestHeaders`, which replace; be careful with anything that adds a header rather than setting it.
+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
-The secret values below are placeholders, not defaults. Replace them with the
-same strong unique secret in Pulse and the proxy, using private configuration
-files or your deployment's secret mechanism. Keep the rendered configuration
-and container environment private too; do not share `docker inspect` or
-resolved Compose output.
+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)
-**docker-compose.yml**:
-```yaml
-environment:
- - PROXY_AUTH_SECRET=secure-secret
- - PROXY_AUTH_USER_HEADER=X-Authentik-Username
-```
-**Traefik Middleware**:
-```yaml
-headers:
- customRequestHeaders:
- X-Proxy-Secret: "secure-secret"
-```
+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)
-```nginx
-location / {
- auth_request /authelia;
- proxy_set_header X-Proxy-Secret "secure-secret";
- proxy_set_header Remote-User $upstream_http_remote_user;
- proxy_pass http://pulse:7655;
-}
-```
+
+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
-1. **Zero Trust Dashboard**: Applications β†’ Add Application.
-2. **Settings**: HTTP Settings β†’ HTTP Headers.
-3. **Add Header**: `X-Proxy-Secret` = `your-secret`.
-4. **Pulse Config**: `PROXY_AUTH_USER_HEADER=Cf-Access-Authenticated-User-Email`.
+
+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
@@ -117,12 +153,25 @@ prints only the HTTP status, not settings, cookies or credential-bearing logs:
trap 'test ! -e "$header_file" || rm -- "$header_file"; rmdir -- "$probe_dir"' EXIT
touch "$header_file"
vi "$header_file"
- curl --disable --silent --show-error --output /dev/null \
- --write-out 'HTTP %{http_code}\n' --header "@$header_file" \
- http://127.0.0.1:7655/api/system/settings
+ if status=$(curl --disable --silent --show-error --output /dev/null \
+ --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.
Otherwise use its existing private backend address over HTTPS with certificate
verification enabled. Do not send forged test identities through a public proxy
diff --git a/scripts/tests/test_authentication_diagnostic_docs.py b/scripts/tests/test_authentication_diagnostic_docs.py
index b3b129fcfc..d5093c39bf 100644
--- a/scripts/tests/test_authentication_diagnostic_docs.py
+++ b/scripts/tests/test_authentication_diagnostic_docs.py
@@ -14,6 +14,7 @@ import shutil
import subprocess
import tempfile
import threading
+import time
import unittest
from test_api_auth_docs import ROOT, TEST_TOKEN, exercise_curl, recording_server
@@ -36,10 +37,14 @@ def blocks(name):
@contextmanager
def proxy_server(status):
requests = []
+ release_stall = threading.Event()
class Handler(BaseHTTPRequestHandler):
def do_GET(self):
requests.append((self.command, self.path, dict(self.headers)))
+ if status == "stall":
+ release_stall.wait(timeout=20)
+ return
self.send_response(status)
self.send_header("Set-Cookie", "synthetic-session-must-not-be-printed")
self.send_header("Location", "/unexpected-redirect-target")
@@ -55,6 +60,7 @@ def proxy_server(status):
try:
yield server.server_address[1], requests
finally:
+ release_stall.set()
server.shutdown()
server.server_close()
thread.join(timeout=5)
@@ -113,7 +119,7 @@ class AuthenticationDiagnosticDocsTest(unittest.TestCase):
self.assertEqual(result.returncode, 22)
self.assertEqual(len(requests), before + 1)
- def exercise_proxy(self, home, port, role, *, editor_exit=0):
+ def exercise_proxy(self, home, port, role, *, editor_exit=0, curl_exit=0):
recipes = blocks("PROXY_AUTH")
self.assertEqual(len(recipes), 1)
recipe = recipes[0].replace("http://127.0.0.1:7655", f"http://127.0.0.1:{port}")
@@ -135,6 +141,8 @@ class AuthenticationDiagnosticDocsTest(unittest.TestCase):
recorder.write_text(
"#!/usr/bin/env python3\nimport json, os, sys\nfrom pathlib import Path\n"
"Path(os.environ['ARGV_RECEIPT']).write_text(json.dumps(sys.argv[1:]))\n"
+ "if os.environ['CURL_EXIT'] != '0':\n"
+ " print('000', end=''); sys.exit(int(os.environ['CURL_EXIT']))\n"
"os.execv(os.environ['REAL_CURL'], [os.environ['REAL_CURL'], *sys.argv[1:]])\n"
)
recorder.chmod(0o700)
@@ -145,11 +153,11 @@ class AuthenticationDiagnosticDocsTest(unittest.TestCase):
env = dict(os.environ, HOME=str(home), PATH=f"{tools}:{os.environ['PATH']}", CURL_HOME=str(home),
XDG_CONFIG_HOME=str(home / ".config"), TMPDIR=str(home),
FIXTURE_HEADERS=str(headers), EDITOR_RECEIPT=str(home / "editor.json"),
- ARGV_RECEIPT=str(home / "argv.json"), REAL_CURL=real_curl, EDITOR_EXIT=str(editor_exit))
+ ARGV_RECEIPT=str(home / "argv.json"), REAL_CURL=real_curl, EDITOR_EXIT=str(editor_exit), CURL_EXIT=str(curl_exit))
for key in list(env):
if key.lower().endswith("_proxy"):
del env[key]
- result = subprocess.run(["bash", "-c", recipe], env=env, capture_output=True, timeout=10)
+ result = subprocess.run(["bash", "-c", recipe], env=env, capture_output=True, timeout=15)
edited = json.loads((home / "editor.json").read_text())
self.assertEqual((edited["directory_mode"], edited["file_mode"]), (0o700, 0o600))
self.assertFalse(Path(edited["file"]).parent.exists(), "temporary credential directory must be cleaned")
@@ -159,6 +167,10 @@ class AuthenticationDiagnosticDocsTest(unittest.TestCase):
self.assertEqual(argv[0], "--disable")
self.assertIn("@" + edited["file"], argv)
self.assertNotIn(TEST_TOKEN, " ".join(argv))
+ for option, value in (("--connect-timeout", "5"), ("--max-time", "10")):
+ self.assertIn(option, argv)
+ self.assertEqual(argv[argv.index(option) + 1], value)
+ self.assertNotIn("--retry", argv)
else:
self.assertFalse((home / "argv.json").exists())
self.assertNotIn(TEST_TOKEN.encode(), result.stdout + result.stderr)
@@ -190,6 +202,60 @@ class AuthenticationDiagnosticDocsTest(unittest.TestCase):
for unexpected in ("X-API-Token", "Authorization", "Cookie", "X-Curlrc-Injected"):
self.assertNotIn(unexpected, headers)
+ def test_proxy_setup_cannot_omit_role_choice_and_authenticated_boundary(self):
+ proxy = " ".join(DOCUMENTS["PROXY_AUTH"].read_text().split())
+ quick = proxy.split("## πŸš€ Quick Start", 1)[1].split("## βš™οΈ Configuration", 1)[0]
+ for phrase in ("every proxy-authenticated user an administrator",
+ "PROXY_AUTH_ROLE_HEADER=X-Authentik-Groups",
+ "PROXY_AUTH_ADMIN_ROLE=<exact-idp-admin-group>",
+ "actual group separator", "Do not remove role gating",
+ "successful IdP authentication", "authenticator is unavailable",
+ "headers-only middleware does not authenticate",
+ "authenticated non-admin and a signed-out session",
+ "existing administrator recovery path"):
+ with self.subTest(phrase=phrase):
+ self.assertIn(phrase, proxy if phrase == "actual group separator" else quick)
+ boundary = proxy.split("## ⚠️ Header Trust Boundary", 1)[1].split("## πŸ“¦ Examples", 1)[0]
+ for phrase in ("replace", "never append", "first", "username and configured role header",
+ "must also come from the successful authenticator", "not be reachable"):
+ self.assertIn(phrase, boundary)
+
+ def test_provider_mappings_are_not_headers_only_deployment_recipes(self):
+ proxy = " ".join(DOCUMENTS["PROXY_AUTH"].read_text().split())
+ examples = proxy.split("## πŸ“¦ Examples", 1)[1].split("## πŸ”§ Troubleshooting", 1)[0]
+ self.assertIn("not complete provider deployment recipes", examples)
+ self.assertNotRegex(examples, r"```(?:yaml|nginx)")
+ for phrase in ("does not configure Authentik", "static username or admin group",
+ "auth_request_set", "failed or unavailable subrequest",
+ "tunnel is a transport, not an Access policy",
+ "does not validate a Cloudflare Access JWT",
+ "replace those headers", "all-users-admin"):
+ with self.subTest(phrase=phrase):
+ self.assertIn(phrase, examples)
+
+ def test_proxy_transport_failure_has_no_role_result_or_retry(self):
+ # Deterministic adverse transport results exercise the copied shell's
+ # exit handling, not a second hand-written request implementation.
+ for curl_exit in (7, 28, 35, 60):
+ with self.subTest(curl_exit=curl_exit), tempfile.TemporaryDirectory() as temporary:
+ result = self.exercise_proxy(Path(temporary), 1, "", curl_exit=curl_exit)
+ self.assertEqual(result.returncode, curl_exit)
+ self.assertEqual(result.stdout, b"")
+ self.assertIn(f"curl exit {curl_exit}".encode(), result.stderr)
+ self.assertIn(b"no role result. Stop here.", result.stderr)
+
+ def test_proxy_stalled_real_transport_stops_and_cleans_up(self):
+ with proxy_server("stall") as (port, requests), tempfile.TemporaryDirectory() as temporary:
+ started = time.monotonic()
+ result = self.exercise_proxy(Path(temporary), port, "X-Proxy-Roles: none\n")
+ elapsed = time.monotonic() - started
+ self.assertEqual(result.returncode, 28, result.stderr.decode())
+ self.assertEqual(result.stdout, b"")
+ self.assertIn(b"no role result. Stop here.", result.stderr)
+ self.assertEqual(len(requests), 1)
+ self.assertGreaterEqual(elapsed, 9)
+ self.assertLess(elapsed, 15)
+
def test_proxy_editor_failure_cleans_up_and_sends_no_request(self):
with proxy_server(200) as (port, requests), tempfile.TemporaryDirectory() as temporary:
result = self.exercise_proxy(Path(temporary), port, "", editor_exit=73)