docs(examples): add Kerberos / NTLM (Integrated Windows Auth) example

[shahzad31]

Summary

Adds examples/kerberos-auth/, a runnable example that shows how to monitor a site protected by Negotiate (SPNEGO/Kerberos) or NTLM using an Elastic Synthetics browser monitor on a Private Location.

Elastic Synthetics drives Chromium through Playwright, and Chromium already has first-class support for Integrated Windows Authentication. The example simply forwards the two relevant Chromium command-line flags through playwrightOptions.args, which the runner already spreads verbatim into chromium.launch({ args }) in src/core/gatherer.ts:

playwrightOptions: {
  args: [
    '--auth-server-allowlist=*.corp.local,corp.local',
    '--auth-negotiate-delegate-allowlist=*.corp.local',
  ],
}

No code changes in src/ are required — this PR documents and demonstrates the pattern.

What's in the example

File	Purpose
README.md	Prereqs (keytab / kinit / krb5.conf / SPN / allowlist semantics), how to run, how to verify the flags reach Chromium, a troubleshooting matrix, and the known limitation that lightweight HTTP monitors are unsupported.
synthetics.config.ts	Wires the two Chromium auth flags and pins the monitor to a Private Location.
protected-site.journey.ts	Navigates to the protected URL and asserts a non-401 authenticated response.
package.json	Lets the example be installed and run standalone with npm install && npm test.

Why browser monitors only

• Browser monitors: supported. Chromium has a full SPNEGO/NTLM stack (GSSAPI on Linux, SSPI on Windows) and will replay the 401 with an Authorization: Negotiate / Authorization: NTLM token once the host is on the allowlist and a ticket is available.
• Lightweight HTTP monitors: unsupported. Heartbeat's Go HTTP client has no native Negotiate/NTLM transport. Called out as a limitation in the README so users aren't misled.
• Managed / global locations: unsupported. The flags only help if the host executing Chromium can authenticate against the realm.

Validation

Flag propagation verified end-to-end on macOS against a mock HTTP server that always replies with WWW-Authenticate: Negotiate, NTLM:

1. Ran a journey with the example config.
2. Snapshotted the live Chromium process with ps auxww while the browser was up; the main headless_shell command line contained:

   --auth-server-allowlist=*.corp.local,corp.local --auth-negotiate-delegate-allowlist=*.corp.local
   

3. Confirmed that when the host does not match the allowlist, Chromium silently ignores the 401 challenge (no Authorization header sent) — matching documented Chromium behaviour.

An end-to-end successful handshake was not run in CI because that requires a real KDC / keytab / ticket cache; the example is structured so a customer with a properly-configured Private Location host can validate layer by layer (see the README's Verifying the flags are applied and Troubleshooting sections).

Customer validation checklist

1. Layer 1 — flags applied. ps -ef | grep -- '--auth-server-allowlist' on the Private Location agent host while a journey is running.
2. Layer 2 — ticket present. sudo -u <agent-user> klist shows a valid TGT; keytab-based renewal is scheduled (cron / systemd timer / kinit -R).
3. Layer 3 — handshake completes. The journey's expect(status).toBeLessThan(400) passes against the real internal URL.

Test plan

• examples/kerberos-auth/ parses with the current runner.
• Example journey loads and executes; assertion fails cleanly with 401 when no credentials are available (correct behaviour).
• Chromium receives both flags on its command line (verified via ps).
• Customer PoC: run layers 1–3 above on a Private Location host joined to their AD realm.

Notes / out of scope

• No changes to src/, no new dependencies, no behaviour change for existing users.
• Native SPNEGO/NTLM support for lightweight HTTP monitors would be a Heartbeat-side change and is out of scope here.

Made with Cursor

[emilioalvap]

LGTM, tested support locally and the example seems sufficiently documented