Ansible/scripts/addons/webgui/docs/CREDENTIALS.md

The behaviors below are retained from2.1.0rc2. Current candidate2.1.0rc9 targets Core3.3.0rc8/schema5 and adds reports/journal described in REPORTS.md and JOURNAL.md. Credential, read-only inventory and OS-permission boundaries here remain unchanged; old version/no-migration statements describe the earlier slice.

One-run credentials through core API 1.0

Core 3.3.0rc8 is authoritative. WebGUI 2.1 does not decrypt Vault or read/export/copy keys. Use native inventory or explicit customer-key loading in New run. Existing usernames, Vault variables and host/group precedence are core/Ansible behavior.

Custom forced username/password override is NOT exposed by core and was removed from this adapter. A supplied connection_password, when the catalog requests it, is a native default and may be overridden by inventory. It is not password-only testing. Become-password UI, key uploads, cross-job password caching and raw task output are not implemented. Terminal features are not automatically API features.

Where to enter a password

Submit the reviewed job first. With approval disabled it queues directly; otherwise an independent enabled administrator approves it. The running queue worker reserves a slot after local core readiness. Job detail then offers Unlock this run. With JavaScript and native dialog support this opens an in-page modal; its link remains an authenticated full-page fallback. Overview and Jobs also surface your eligible reservations in Needs your attention. Only the requesting account may use this form. All requested fields derive from PreparedRun. A present customer Vault is conservatively required even when the catalog's require_vault flag is false. An encrypted customer key can use an explicit key passphrase or Core's literal vault_linux_ssh_key_passphrase lookup. The grouped Use customer Vault / Enter separately choice appears only for that alternative requirement with a Vault source. A separately required key passphrase is never made optional.

A reservation without secrets lasts5minutes. After submission, hand-off/preparation/ start must fit60seconds; execution has the separate bounded job timeout. An expired or failed attempt does not retain credentials for the next attempt. Scheduled jobs collect secrets only when their time/window/approval and worker are ready.

Transport and processing

Existing verified HTTPS to NPM/backend and loopback final hop are assumed configured by the operator. Dedicated POST bodies, CSRF/origin/session authorization and8KiB body limit remain. Passwords are literal, max2048 UTF8 bytes each, no CR/LF/NUL. No client-side hash substitution. Browser fields clear on navigation and never enter HTMX history/localStorage. Raw body/error logging remains prohibited.

The web identity sends private bounded local frames to its worker, then to the executor. The executor starts aimctl with a separate inherited secret pipe FD, not stdin request JSON, argv, environment or a password file. Core owns its provider, key agent and native credential helpers. WebGUI does not reinterpret Vault values.

Python release of references is not guaranteed RAM erasure. Review swap/dumps, proxy request buffering and access to the service accounts. A compromised authorized web process may exercise the local core client authority; this is not tenant isolation. No automatic data/file-permission repair or credential fallback is performed.

Qualification

aim-web credential-check now means public capability/authorized metadata checking. It does not test decryption or remote auth and requires no pytest in production. core-check --customer ... --playbook ... --host ... --key-mode customer additionally runs documented local readiness. Real SSH/WinRM acceptance remains an operator gate. Use the included disposable test instructions for API integration; fake native fixtures do not certify real Ansible or controller systemd permissions.

Dialog lifecycle and recovery

The dialog loads only after an explicit user action. Its form lives outside status/attention polling so typing is not discarded by an HTMX replacement. It shows the frozen customer/playbook/mode and target count. Show/Hide never changes what is submitted, and pasting is not blocked. Escape/Close/Not now clear fields, including visible-password inputs, and return focus without canceling the job. Backdrop taps do not dismiss it. A small visual viewport constrains the dialog's internal scroll area rather than growing the page.

Only required/supported Core fields are rendered. For the Vault/key alternative, the default sends just the Vault password; Enter separately adds a required key-passphrase field. Switching back clears that field. No source-radio name or extra scope/identity field is sent to the API. A plain HTML form with JavaScript unavailable exposes the optional separate field with its explanation and does not submit disabled source controls.

The countdown uses the server deadline, not a new five-minute timer on each opening. Polling does not renew it. Submission clears live form values and disables repeat clicks. A 202 accepted response means only that the existing worker claimed the handoff. Core validation and remote authentication happen later. A lost acknowledgement must not cause automatic POST retry: the client locks the form and polls owner-only status. Worker single-claim/session/scope checks remain authoritative across tabs.

The canonical POST route is /api/v2/runs/{id}/credentials; the existing /api/v2/jobs/{id}/credentials is kept as an alias. Both use the same five-attempts-per-minute requester throttle and existing private worker socket. GET /api/v2/runs/{id}/credential-status is non-secret status only. It never reports a password as correct, requests new work or extends the reservation.