Feature Request: Interactive OAuth Login for Headless Environments and AI Coding Agents

[Damecek]

Summary

Please add a way to complete sf org login web when the machine running the CLI has no browser: print the authorization URL, let the developer log in from a browser on any other device, and accept the resulting callback URL pasted back into the same waiting command. Something like:

sf org login web --manual --alias my-org

The flag name is open for discussion. No new server-side API is needed: the flow is the existing Authorization Code + PKCE web server flow with the existing PlatformCLI connected app. The only change is how the CLI receives the redirect: from stdin instead of from a local HTTP listener.

A working proof of concept exists as a standalone plugin: https://github.com/Damecek/sf-plugin-remote-login (sf org login remote). It was verified end to end from a headless Docker container with the login completed on an iPhone. Details below.

Why this matters now

Developer workflows have changed. A growing share of development work is delegated to autonomous coding agents that run on remote Linux hosts, containers, home servers or cloud dev environments. The developer talks to the agent from a phone, a web UI or an SSH session. The agent has a terminal but no desktop and no browser. Today, when such an agent needs a Salesforce org it has not been authenticated to, sf org login web cannot finish, and the developer has to switch to a machine with a desktop just to authorize the CLI.

Human approval stays in the loop. This is not a request to bypass or weaken anything. The developer still goes through the normal Salesforce login page in a trusted browser, including SSO, MFA, IP restrictions and connected-app policies. The only difference from today is that the browser is on a different device than the CLI.

JWT is not an equivalent replacement. JWT bearer auth is the right tool for unattended, pre-configured automation. For an ad hoc development session it requires creating a connected app, a certificate, pre-authorizing profiles, and distributing a private key to the agent host, per org, before the first login. The scenario here is the opposite: a human wants to grant an agent access to an org right now, with nothing prepared.

Device Flow is not being asked for. We understand why org login device was removed (#3368: restrictions on uninstalled connected apps and the Device Flow policy on the default app). The proposed flow is the supported web server flow with PKCE, which #3668 just made mandatory on PlatformCLI. It does not need Device Flow to be re-enabled.

Remote and mobile-first. The flow works from an iPhone, a tablet, a browser-based IDE, a container, or an SSH session, because the only thing that has to move between devices is two URLs.

Proposed behaviour

1. The CLI builds the authorization URL exactly as it does now (AuthInfo.getAuthorizationUrl with a jsforce OAuth2 instance that holds the PKCE verifier, random state, prompt=login, default scopes, redirect_uri=http://localhost:1717/OauthRedirect).
2. Instead of calling open() and starting WebOAuthServer, it prints the URL and short instructions, then waits on a hidden prompt (secretPrompt).
3. The developer logs in on any device. The browser is redirected to http://localhost:1717/OauthRedirect?code=...&state=..., which does not load on that device. That is fine: the code is in the address bar. The developer copies the address and pastes it into the waiting command.
4. The CLI validates the pasted URL: exact origin and path of the configured redirect URI, state equal to the one it generated (constant-time compare), no error parameter, code present.
5. AuthInfo.create({ oauth2Options: { ...config, authCode }, oauth2 }) exchanges the code with the original PKCE verifier, AuthInfo.save() persists it, handleAliasAndDefaultSettings applies --alias, --set-default, --set-default-dev-hub. Output and --json are the same as today.

Everything after step 3 is existing @salesforce/core code. In the proof of concept the whole feature is about 150 lines including messages, with no new dependencies beyond what plugin-auth already uses.

Proof of concept

Repository: https://github.com/Damecek/sf-plugin-remote-login (MIT)

Install and use:

echo y | sf plugins install https://github.com/Damecek/sf-plugin-remote-login.git
sf org login remote --alias my-org
# open the printed URL on any device, log in, paste the final http://localhost:1717/OauthRedirect?... address
sf org display --target-org my-org

What was verified (full log in the repo's VERIFICATION.md):

• Headless Linux: Docker node:22-bookworm-slim, no DISPLAY, no X socket, no browser binaries, command run under a pseudo-terminal. The plugin was installed from the git URL with sf plugins install.
• Human step: iOS Safari on an iPhone, standard username/password login to a production org via login.salesforce.com. Safari showed "cannot open the page" for the localhost redirect; the full URL was copied from the address bar.
• Result: Successfully authorized <user> with org ID <id>. Afterwards, in the same container and using only the stored auth: sf org list auth (Auth Method: web), sf org display (Connected), sf data query --query "SELECT Id FROM User LIMIT 1" (1 record). The auth file has the same fields as one written by org login web.
• Automated: 24 mocha tests (URL generation, PKCE and state, callback validation incl. wrong origin/port/path, state mismatch, OAuth error responses, missing code, expired or replayed code, network failure, timeout, cancellation, alias handling, token redaction), lint, typecheck, and a GitHub Actions job that installs the plugin into sf from the commit.

Not verified: SSO logins (same flow as org login web, but not exercised), Android browsers, Code Builder.

Security considerations

• Same OAuth flow, same connected app, same scopes, same token storage as org login web. PKCE verifier and state are random, held in memory, never printed.
• The pasted callback URL is read through a masked prompt and never echoed, logged or returned in --json. The authorization code is single use, short lived, and useless without the PKCE verifier held by the waiting process.
• Strict validation before any exchange: exact redirect origin and path, matching state, OAuth error surfaced, missing code rejected.
• Trust model matches the local callback server: anyone who can type into the waiting terminal could paste a URL from their own login, exactly as anyone who can reach localhost:1717 could today.
• No ports are opened, no relay or hosted service is involved, nothing is transferred between machines except the two URLs.

One honest trade-off: copying a long URL by hand is clunky, and the "cannot connect" page after login looks like an error until you have read the instructions. A dedicated redirect page that just displays the URL to copy would improve this, but it is not required.

Relation to earlier threads

• sf org login web does not work when SF_CONTAINER_MODE is set to true #3415 reported that org login web fails in containers; the answer was that headless web login is not supported.
• Headless environments (especially containers) should support `sf org login web` #3426 asked for the CLI to print a one-time URL in container mode; the recommendation was JWT. The request stalled because printing the URL alone does not help: the redirect still targets localhost on the CLI machine. This proposal adds the missing half (accepting the redirect URL from stdin) and shows it working against the current PKCE-mandatory PlatformCLI app.
• Restricted usage of the Salesforce CLI connected app #3368 explains the Device Flow removal; this proposal does not depend on Device Flow.

Happy to turn the proof of concept into a PR against plugin-auth if the team is open to the idea.

[Damecek]

Implementation PR against plugin-auth, adding --manual to sf org login web: salesforcecli/plugin-auth#1562. Same logic as the proof of concept, 27 new unit tests, no change to the OAuth flow, connected app, scopes or storage.