External credential helpers

The Watcher client can invoke your organization's CLI to obtain a token for its reverse proxy. The proxy validates the token and forwards the authenticated identity to your Watcher deployment. Your CLI owns sign-in and identity-provider integration.

Before you start

• Your deployment uses proxy authentication, with a gateway that accepts Authorization: Bearer <token>. Configure the gateway to validate tokens and replace client-supplied identity and role headers. Restrict direct access to the backend.
• Install a trusted helper on the client machine. It must work without interactive stdin, a browser, or your shell's environment. Complete any initial company sign-in separately.
• Use an absolute executable path. The resolved executable and its installation directories must be owned by the client user or root, without group or world write permission. An owner-only wrapper can adapt your existing CLI's arguments and output.
• Remove competing authentication for this destination: captured Authorization or x-api-key headers, stored Watcher SSO credentials, and WATCHER_API_KEY or XYLON_API_KEY. Watcher refuses conflicts rather than choosing an identity. Keep any required routing headers.

The helper runs with the client's OS permissions. Configure only software you trust. This feature does not sandbox the helper or prevent another process with unrestricted access to the same account from modifying it.

Configure and verify

1. Select your deployment if it is not already selected:

   watcher target set --url https://watcher.example.com

2. Configure the helper without running it:

   watcher auth helper set --cache-ttl 300 --timeout 5 -- /opt/company/bin/watcher-token

   Put literal helper arguments after the executable. Watcher does not evaluate shell expressions, expand variables, or search PATH for the executable.

   Repeating set with the same executable, arguments, environment, and timing settings leaves the configuration and cached token unchanged. Retry cooldowns also remain in place. Changing these settings clears the cached token. Use watcher auth helper refresh to request renewal without changing the configuration.

3. Verify gateway acceptance:

   watcher auth helper check

   Success reports Credential helper authentication succeeded. No token is displayed. Start Watcher normally to maintain credentials in the background. Requests can also acquire tokens when the background client is absent.

Each command accepts --url https://watcher.example.com; otherwise it uses the selected deployment. Configuration is isolated by scheme, host, port, and API path. The base URL and its /api form select the same configuration. HTTPS with certificate verification is required; loopback HTTP is allowed for local testing.

Helper contract

Return one JSON object on stdout:

{"token": "opaque-token"}

Watcher ignores unknown fields. Helpers may add optional metadata, but must not rely on clients using it. Expiry fields are ignored; --cache-ttl still controls reuse. A change that requires new client behavior needs a new protocol version.

Property	Requirement
stdout	One UTF-8 JSON object with a required string token field. JSON whitespace is allowed. No raw token, progress messages, or extra JSON values.
Token characters	Letters, digits, ., _, ~, +, /, and -, followed by optional = padding. Between 1 and 16,384 decoded ASCII bytes. No Bearer prefix or whitespace in the token.
Exit code	0 for success; 10 when external sign-in is required; other nonzero exits are failures.
stdin	Closed. Complete interactive sign-in outside Watcher.
stderr	Discarded. Combined stdout and stderr must not exceed 64 KiB, including JSON syntax and ignored fields.
Timeout	Default 5 seconds, configurable from 1 to 30 with --timeout. Includes waiting for another acquisition. Cleanup can take one additional second. A shorter request timeout limits acquisition too.
Cache	Default maximum reuse age 300 seconds; configurable from 1 to 3,600 with --cache-ttl. This is not token expiry metadata.

Watcher rejects malformed output and invalid decoded tokens without trimming or changing token values. It alone constructs the Authorization header. The helper cannot choose another header or destination. Helper-authenticated requests do not follow redirects.

The helper receives these environment variables:

Variable	Value
WATCHER_CREDENTIAL_HELPER_VERSION	1
WATCHER_CREDENTIAL_HELPER_URL	The canonical API base URL, including /api
WATCHER_CREDENTIAL_HELPER_FORCE_REFRESH	0 normally; 1 after rejection or an explicit refresh

When force refresh is 1, bypass your CLI's rejected cached credential or return a sign-in/failure code. Never print an old rejected token as a successful refresh. Do not daemonize; Watcher cleans up the invocation's process group.

Watcher supplies account-derived HOME, USER, and LOGNAME, a system-only PATH (/usr/bin:/bin:/usr/sbin:/sbin), and a UTF-8 locale. It runs in the account's home directory. It does not inherit arbitrary caller environment variables, including language import and dynamic-loader settings.

Pass required environment values explicitly at setup, for example:

watcher auth helper set --env COMPANY_AUTH_PROFILE=engineering -- /opt/company/bin/watcher-token

Repeat --env NAME=VALUE as needed. Explicit values are trusted configuration and can affect how the helper executes. The three protocol variables above are reserved. Avoid putting secrets in shell history or command arguments. Watcher stores explicit environment values privately and never displays them in show.

Renewal and recovery

Watcher shares acquisitions across processes and reuses cached tokens. The background client renews near 80% of the cache interval. A 401 can reuse a peer's replacement or trigger one renewal and one replay of a buffered request. A 403 does not trigger renewal. Acquisition failures and rejected tokens have a shared 30-second retry cooldown. After a failed forced renewal, retries keep bypassing the helper cache until a replacement succeeds. There is no fallback to another credential source.

Persistent server rejection opens authentication backoff and disables monitoring hooks under the existing proxy-auth policy. The coding agent's own permissions apply during this interval. Automatic authenticated recovery probes run at most once every five minutes; printing a new token alone does not prove recovery.

If the helper reports sign_in_required, complete your company's sign-in outside Watcher. Background acquisition retries without a client restart. To force renewal and check acceptance immediately:

watcher auth helper refresh

Use watcher auth helper show to inspect the executable, argument count, environment variable names, and timing settings. watcher doctor auth can invoke the helper to diagnose acceptance. watcher doctor dump takes a local helper snapshot and does not invoke it. Gateway error text and helper stdout/stderr are excluded from diagnostics; review support bundles before sharing them.

Headless hosts, containers, and fleets

The helper protocol works on macOS and Linux without a GUI or service manager. WSL runtime validation is pending. The intended WSL configuration uses Linux-native helpers and keeps helper state on the distribution's Linux filesystem. Windows executables, PowerShell integration, Windows credential stores, and shared state on Windows mounts are outside this feature's contract.

In a container, install the helper and provide its own IdP state to the container user. Run setup as that user. Watcher's helper files must be owned by the process's effective UID, with directories mode 0700 and files mode 0600. A bind mount that appears owned by a different UID is rejected. Keep the container's Watcher state separate from the host's state; persist it in a private writable volume if it must survive replacement. See Containers.

For MDM rollout, run watcher auth helper set as each target user after installing the helper. Running it as root configures root's state, not the developer's. Use the CLI instead of constructing destination hashes or distributing a token cache. Ensure the helper can renew under the user's background launch environment.

Configuration and cache live under ~/.apollo_monitor/credential_helpers/<destination-digest>/ (or the launch-selected APOLLO_MONITOR_HOME). config.json contains the command and explicit environment, state.json contains the cached token and renewal status, and .lock coordinates processes. Treat both JSON files as secrets. The lock remains after removal so concurrent processes keep using the same lock.

Remove the helper

watcher auth helper clear

This removes the selected configuration and cached token after any active acquisition finishes. It does not revoke tokens or sign the user out of the company's IdP. Configure another authentication method explicitly if needed. Older Watcher clients ignore helper configuration; downgrading requires an authentication method that the older client supports.