credentials

Local credentials (noetl credential, credential: aliases)

Since 5.2.0 (#96). --runtime local has no server keychain, so playbook credential aliases resolve from a local store. Two consumers use it: agent steps and http steps.

Source: executor/src/local_credentials.rs (store + Google refresh), src/credential_cli.rs (command), tools_bridge::resolve_http_auth_header (http auth).

Resolution

credential: <alias> resolves, in order:

1. NOETL_CREDENTIAL_<ALIAS>: alias upper-cased, non-alphanumerics as _ (gmail-work → NOETL_CREDENTIAL_GMAIL_WORK). Used when non-blank.
2. The file <dir>/<alias>. <dir> is $NOETL_CREDENTIALS_DIR, else $XDG_CONFIG_HOME/noetl/credentials, else ~/.config/noetl/credentials.

If the alias is found nowhere, or the value is blank, the step fails before any network call, and the error names both places.

Guards

Guard	Prevents
Alias must match [A-Za-z0-9._-]+ and not start with .	a templated alias (gmail-{{ workload.account }}) naming a path outside the store
Files with any group or other permission bits are refused, with the chmod 600 to run	a key readable by other users being used silently
store writes atomically (temp file + rename), directory 700, file 600	half-written or world-readable credential files
A google_oauth document is refused as a bearer / api_key value	a refresh token being sent verbatim to the step's URL
No subcommand prints a value; list shows alias, type and mode only	secrets in terminal scrollback

http auth types

auth.type is accepted as an alias of auth.provider.

type	header	credential
gcp / google / adc	Authorization: Bearer <ADC token>	none (unchanged)
bearer	Authorization: Bearer <value>	required
api_key	<auth.header, default X-API-Key>: <value>	required
google_oauth	Authorization: Bearer <access token>	required: a refresh-token document

google_oauth exchanges the stored refresh token at its token_uri, and caches the access token per alias (in-process) until 60 s before expires_in. On invalid_grant, the error tells you to re-run noetl credential google <alias>.

noetl credential

Command	Does
set <alias>	hidden prompt (TTY) or stdin (pipe) → store
google <alias> --client-secret-file <f> [--scope s]… [--login-hint e] [--port p] [--no-open]	installed-app OAuth: loopback http://127.0.0.1:<port>/, PKCE S256, access_type=offline, prompt=consent. Exchanges the code and stores {type: google_oauth, client_id, client_secret, refresh_token, token_uri, scopes, account}. account is read from the Gmail profile when the scope is a Gmail one. Default scope gmail.readonly; short names expand to https://www.googleapis.com/auth/<name>.
list	alias, type (secret / google_oauth), mode; warns if not private
path	the store directory

--client-secret-file takes the JSON downloaded for a Desktop app OAuth client, which has an installed section; a web section is also accepted. The command reuses the CLI's loopback PKCE callback (wait_for_pkce_callback), whose messages say "OAuth" rather than "Auth0" since 5.2.0.

Google-side constraint: while the OAuth app is in Testing, Google expires refresh tokens after 7 days, and only listed test users can consent (access_denied otherwise). Setup steps: agent-playbooks wiki: Connect Gmail.

Related

kind: agent · tracking: noetl/ai-meta#474