Authdog
Back to journal
SDK IntegrationCLIOAuth

Browser-based CLI authentication

Command-line applications can authenticate users through a browser OAuth flow and redeem the completed session.

From the changelog: Browser-based CLI authentication

Authdog Team

2 min read
Centered Authdog mark with an angled CLI word plate on a grainy indigo wash with dashed terminal frames

A CLI cannot host a login form. Operators still need a real user session, not a long-lived shared secret pasted into a terminal. Authdog now bridges browser OAuth to the waiting command-line process and lets that process redeem the completed session once.

This is the longer note behind the May 17 changelog entry.

How it works

The CLI starts a short-lived login bridge (cli_oauth_sessions). The browser runs the normal hosted OAuth flow. The identity service embeds CLI correlation in the OAuth state parameter:

  • clises: plus a UUID v4 session id
  • optional clidb: plus a loopback finish URL

Loopback redirects are http://127.0.0.1 only, with a port and path, and no query, hash, or credentials. After sign-in completes, the bridge stores access and refresh tokens for eight minutes.

Two one-time redemptions exist:

  • Poll — GET /api/v1/cli/oauth/poll?session=<uuid> returns pending until tokens exist, then complete with the tokens and deletes the row
  • Redeem — if the browser was sent to a loopback URL with ?grant=…, POST /api/v1/cli/oauth/redeem exchanges that 64-character hex grant for the same tokens and deletes the row

Expired rows are removed on poll and redeem. A used grant or session cannot be collected again. The browser lands on /cli/oauth/done/:environmentId when no loopback URL was supplied.

State that is not a valid CLI session id is ignored. Tokens are returned with Cache-Control: no-store.

Set it up

Use the Authdog CLI against an environment that already has an OIDC client and hosted sign-in:

  1. Start the CLI login command so it opens the browser (or prints the URL).
  2. Complete sign-in on the hosted Account Portal.
  3. Return to the terminal. The CLI polls the bridge or redeems the loopback grant.

Do not paste tokens from the done page. The page only confirms who signed in.

Trust boundaries

The bridge is a one-shot handoff, not a refresh-token store. Anyone who can read the poll session id or the loopback grant during the eight-minute window can collect the tokens. Bind the session to the local process and treat the grant as a secret.

Loopback is localhost only. A remote redirect is rejected. Browser completion is not server authentication by itself — the CLI must redeem the bridge.

Try it

Run CLI login against a non-production environment and confirm the terminal receives tokens after the browser tab closes. Product overview is on CLI. The original release note is in the changelog.

More from Authdog
ShareLinkedInX