Skip to content

feat: add OAuth sign-in and a2a auth commands - #146

Open
mykytanetipa wants to merge 1 commit into
mykytanetipa/sdk-oauth-bumpfrom
mykytanetipa/sdk-oauth-cli
Open

mykytanetipa wants to merge 1 commit into
mykytanetipa/sdk-oauth-bumpfrom
mykytanetipa/sdk-oauth-cli

Conversation

@mykytanetipa

@mykytanetipa mykytanetipa commented Nov 8, 2026 •

Copy link
Copy Markdown

Adds OAuth sign-in to the a2a CLI, built on the a2a-go OAuth client. Once OAuth is turned on, a command whose agent needs a token signs the user in, stores the grant and runs again. Later commands reuse the grant and refresh it without prompts:

$ a2a send -a https://agent.example.com --oauth auto hello
To authorize, open:
https://login.example.com/authorize?client_id=...&code_challenge=...&resource=https%3A%2F%2Fagent.example.com&...
Authorized. Grant saved for https://agent.example.com.

$ a2a auth login https://agent.example.com --device
To authorize, open: https://login.example.com/activate
Enter code: WDJB-MJHT

$ a2a send -a https://agent.example.com --oauth cached "from a script"   # never signs in; exit 4 without a grant

Key changes

  • OAuth is off by default, so agents you reach with other credentials work as before. You turn it on with --oauth auto or with oauth: auto in the user config. A repo's .env can't turn it on. While it's off, a 401 asking for a Bearer token comes with a hint on how to sign in.
  • Commands sign in on first use in the browser, or with the device flow when given --device. A sign-in only starts when stderr is a terminal. --oauth cached never signs in, which suits scripts, and exits 4 when there's no usable grant.
  • a2a auth login, list, get and logout manage grants, and auth get redacts tokens unless given --reveal. Logout removes the grant for the URL you pass and for card interfaces below it. Grants for other interfaces on the same host are only listed, since they may belong to another agent.
  • The a2a-go OAuth plugin attaches and refreshes tokens over both HTTP and gRPC. A 401 without a Bearer challenge is reported as the agent's error, not as a rejected grant.
  • An Authorization header you set with --auth, --svc-param or a credential helper always wins, and OAuth leaves that request alone.
  • --oauth-clients sets the client for each authorization server. Without a match, a2a uses its Client ID Metadata Document, https://a2a-protocol.org/oauth/a2a-cli.json, with servers that support it.
  • Grants are stored in ~/.config/a2a-cli/oauth/grants.json, readable only by you and locked across processes. When --insecure comes from a discovered .env, no OAuth token is sent over plaintext gRPC.

This builds against the a2a-go OAuth client, which isn't released yet, so go.mod points at that branch for now. With that SDK, a JSON-RPC error without a JSON-RPC body, such as a 502 from a proxy, is reported as A2ACLI_ERR_PROTOCOL instead of A2ACLI_ERR_INTERNAL. Exit codes are unchanged.

Tested

  • CLI tests against oauthtest and real gRPC and HTTP agents, and an end-to-end run against a demo agent and authorization server.

Refs #98

@mykytanetipa
mykytanetipa added this pull request to stack #148 November 8, 2026 22:02
@mykytanetipa
mykytanetipa force-pushed the mykytanetipa/sdk-oauth-cli branch from 336f9d2 to c6299c3 Compare November 8, 2026 23:49
@ConnorMoss02

ConnorMoss02 commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Ran this against a2a-go's oauthtest server with a few protected agents. Browser and device sign-in, silent refresh with rotation, --oauth cached, step-up and logout revoking at the server all worked for me, and a repo .env couldn't turn OAuth on.

Logout can reach other hosts though. grantsForAgent (auth_list.go:124) picks up any grant whose resource is in the card's supportedInterfaces. I served a card at 127.0.0.1:18999 listing another agent's URL, and a2a auth logout http://127.0.0.1:18999 deleted that agent's grant. Limiting it to interfaces on the same origin would fix it.

A repo .env also can't turn OAuth on, but it can still set insecure, endpoint and transport (root.go:267 only blocks unix-socket, credential-helper, ca-cert and the oauth flags). With oauth: cached in my user config, a .env pointing at host:port over gRPC with A2ACLI_INSECURE=true sent the stored grant in cleartext, with just the usual --insecure warning. Adding insecure to that list, or not attaching a grant to insecure gRPC unless the flag came from the command line, would close it.

A plain 401 without a Bearer challenge also gets treated as a bad grant. task list against the test agent returns UNAUTHENTICATED with no WWW-Authenticate, and the CLI refreshed twice and then said the stored grant was rejected, even though task get with the same token worked.

Use a2aclient/oauth from a2a-go for discovery, sign-in, refresh and the
client plugin that attaches tokens, and keep only what is specific to
the CLI:

- internal/oauthstore: the grant file in ~/.config/a2a-cli/oauth with
  its cross-process lock, which the Manager is given as its Locker, and
  which follows the a2a-go Store contract (grants by ID, Get reports
  ErrGrantNotFound, results are copies); on Windows a write retries
  briefly when another process has the file open. The --oauth-clients
  flag, with omit_resource and unknown fields rejected everywhere, and
  the a2a-cli Client ID Metadata Document.
- internal/cli: --oauth, a2a auth login/logout/list, OAuth grants in
  a2a auth get, signing in and retrying when an agent requires it, the
  prompts for the browser and device flows with the redirect path the
  CIMD document lists, and exit code 4 with CREDENTIALS_MISSING or
  AUTH_FAILED.

OAuth is off by default for agent calls, so agents reached with other
credentials work as before; users turn it on with --oauth auto|cached,
oauth: auto in the config, or A2ACLI_OAUTH, but not from a discovered
.env. The a2a auth commands work in any mode, and the grant store is only
opened when OAuth is used, so other commands still run without a home
directory. With OAuth off, a 401 that asks for a Bearer token, including
one for the agent card, gets a hint to sign in and retry with --oauth
auto, unless the request carried an Authorization header of the user's.

With OAuth on, the Manager's plugin attaches the stored grant, refreshes
a token the agent rejects and repeats the call once, and reports calls
that need a sign-in. Explicit credentials win: a credential helper runs
as a plugin before OAuth, so a call that carries its Authorization, or
one from --auth or --svc-param, is left to that credential, 401
included. When the user passes any --svc-param, has a credential helper
for the agent's host, or uses --unix-socket, a card that requires OAuth
doesn't stop the request before it is sent, also when its OAuth
requirement can't be resolved, and OAuth signs in only when the agent
answers with a Bearer challenge. A 401 without one is reported as the
agent's error. Duplicate oauth-clients entries for one server are a
usage error naming them, and auth logout refuses an argument that isn't
an http(s) URL. When --insecure comes from a discovered .env, no OAuth
token is sent over plaintext gRPC.

A protected agent card is not an A2A call: its request carries the token
from Manager.Token when a grant is stored, and its 401 leads to the
sign-in through Manager.Discover, both when a command signs in and in
auth login. auth login makes a real GetTask call, so it finds the
requirement the way other commands do, including from a 401 to an agent
that answers a bare GET with 404 or 405; when that needs no sign-in it
reads the card or probes the interface with Manager.Discover. When no
client registration matches, the error names the oauth-clients entry to
add, or for a flow the card declares inline, the token endpoint whose
server needs one. Ctrl-C during a sign-in is reported as an interrupted
authorization.

auth get and auth logout select the grant for exactly the URL given, and
read the agent card to also select the grants for its interface URLs at
or below that URL and, when the URL has a path, those below it. Grants
for the card's other interfaces on the same origin, which may belong to
other agents on a host that routes agents by path, are only listed, and
interfaces on other origins are ignored, so one agent's card can't
select another agent's grants. When the card can't be read they select
only the exact grant. Other grants that may apply, such as one for the host
shared by sibling agents, are listed by auth get and kept by auth logout
with the command that removes each. Logout revokes through
Manager.Revoke, which removes the grant even when the server can't
revoke it. auth get with nothing stored fails with CREDENTIALS_MISSING,
and its JSON always has the same keys.

a2a server --proxy never uses OAuth for its upstream calls. Other
commands only start a sign-in when stderr is a terminal, which
/dev/null is not.

a2a-go diagnostics go to the logger in the command context: with
--verbose they are printed like other diagnostics, and otherwise the
OAuth ones stay hidden.
@mykytanetipa
mykytanetipa force-pushed the mykytanetipa/sdk-oauth-cli branch from c6299c3 to 742b432 Compare November 15, 2026 14:53
@mykytanetipa

Copy link
Copy Markdown
Author

Ran this against a2a-go's oauthtest server with a few protected agents. Browser and device sign-in, silent refresh with rotation, --oauth cached, step-up and logout revoking at the server all worked for me, and a repo .env couldn't turn OAuth on.

Logout can reach other hosts though. grantsForAgent (auth_list.go:124) picks up any grant whose resource is in the card's supportedInterfaces. I served a card at 127.0.0.1:18999 listing another agent's URL, and a2a auth logout http://127.0.0.1:18999 deleted that agent's grant. Limiting it to interfaces on the same origin would fix it.

A repo .env also can't turn OAuth on, but it can still set insecure, endpoint and transport (root.go:267 only blocks unix-socket, credential-helper, ca-cert and the oauth flags). With oauth: cached in my user config, a .env pointing at host:port over gRPC with A2ACLI_INSECURE=true sent the stored grant in cleartext, with just the usual --insecure warning. Adding insecure to that list, or not attaching a grant to insecure gRPC unless the flag came from the command line, would close it.

A plain 401 without a Bearer challenge also gets treated as a bad grant. task list against the test agent returns UNAUTHENTICATED with no WWW-Authenticate, and the CLI refreshed twice and then said the stored grant was rejected, even though task get with the same token worked.

Agree, all three are fixed: Logout now only removes grants at or below the URL you pass, so your 18999 repro leaves the other agent's grant alone. When --insecure comes from a discovered .env, OAuth tokens aren't sent over plaintext gRPC. And a 401 without a Bearer challenge is passed through as is, so task list just shows UNAUTHENTICATED.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants