Skip to content

feat: keep OAuth tokens in the OS keychain - #147

Open
mykytanetipa wants to merge 1 commit into
mykytanetipa/sdk-oauth-clifrom
mykytanetipa/sdk-oauth-keychain
Open

mykytanetipa wants to merge 1 commit into
mykytanetipa/sdk-oauth-clifrom
mykytanetipa/sdk-oauth-keychain

Conversation

@mykytanetipa

@mykytanetipa mykytanetipa commented Nov 8, 2026 •

Copy link
Copy Markdown

Adds an OS keychain store for OAuth grants. With --oauth-store keychain, tokens go to the macOS Keychain, Windows Credential Manager or Linux Secret Service, and only the rest of each grant stays on disk:

$ a2a auth login https://agent.example.com --oauth-store keychain
$ a2a send -a https://agent.example.com --oauth auto --oauth-store keychain hello

Key changes

  • Each access and refresh token is its own keychain entry, which helps stay within platform size limits. The rest of each grant goes in keychain-grants.json, without tokens.
  • Listing grants only reads that index, so auth list and calls to agents without a grant never touch the keychain or wait on a locked one. A command reads tokens only for the grant it uses.
  • Without a keychain, saving a grant fails instead of writing tokens to disk. The README lists the macOS and Windows size limits, which tokens with many claims can exceed. An invalid --oauth-store is a usage error for every command.
  • The refresh token is written first, so a rotated one isn't lost if the access token can't be stored. The old access token is then removed, so the grant refreshes on next use. A grant that can't be stored the first time leaves no keychain entries behind for logout to miss.

Tested

  • Store tests with a fake keychain, CLI tests, and an end-to-end run against the real Secret Service.

Refs #98

@mykytanetipa
mykytanetipa added this pull request to stack #148 November 8, 2026 22:02
@mykytanetipa
mykytanetipa force-pushed the mykytanetipa/sdk-oauth-keychain branch from b451824 to d73e1ca Compare November 8, 2026 23:49

@rahul05ranjan rahul05ranjan left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I traced the grant lifecycle against the a2aclient/oauth manager this builds on, and the design holds together well: Grant.apply only overwrites the refresh token when the server actually rotates it, so the Delete-on-empty arm in KeyringStore.Put only fires for grants that genuinely have no refresh token; forgetAccessToken keeps the refresh token and the store correctly drops just the access entry; and GrantKey.ID() covers issuer/client/resource/scopes but not GrantedScopes, so keychain entry names stay stable across refreshes. The refresh-token-first write ordering is a nice touch for rotation, and the index-file rename (Name) so a FileStore can't mistake a keychain grant for a tokenless file grant is the right call. The TestOAuthFlagsIgnoredFromDiscoveredEnv extension (.env must not choose the store) is a good security-conscious addition too.

One edge the tests don't pin down: when the access-token write fails after the refresh-token write (the ErrSetDataTooBig path in TestKeyringStoreRotatedRefreshToken), the previous access token stays in the keychain, and the next Get pairs it with the new refresh token — a1 + r2 in the test's terms. The test asserts RefreshToken == "r2" but not AccessToken, so either outcome passes. If keeping the stale access token is intended (it's a secret the user already had, and it may still be valid), an explicit AccessToken == "a1" assertion would document that; if not, deleting the access entry before returning the error would make the failure atomic. As-is, a server whose tokens are consistently over the keychain size limit will keep erroring on every refresh and silently keep using the old access token in between.

Minor observation on fill: a hard read error (locked keychain, Secret Service hiccup) on either token aborts the command rather than degrading to a tokenless grant. That's consistent with the no-silent-fallback stance and probably right, just noting the CLI will hard-fail on a locked keychain where --oauth-store file would have kept working.

@ConnorMoss02

Copy link
Copy Markdown
Contributor

Ran the store tests and the fake-keychain paths (didn't want to test against my real keychain). The refresh-token-first ordering works as described: a failed access-token write during rotation keeps the new refresh token.

If the first save fails partway, say the access token is too big or the keychain write is denied, the refresh token is already in the keychain but the index has no entry. auth logout --all never finds it, so a long-lived token stays behind. The same happens if the index write fails after both keychain writes. Deleting the just-written entries on failure, or writing the index entry first, would cover it.

Also worth noting in the README: on macOS go-keyring caps a secret at about 3 KB after base64, and Windows Credential Manager at 2.5 KB. Entra tokens with group claims can go over that, and you only find out after finishing the browser sign-in.

Add --oauth-store keychain, which keeps access and refresh tokens in the
macOS Keychain, Windows Credential Manager or Linux Secret Service, one
entry per token named after the grant's ID, and the rest of each grant
in keychain-grants.json next to grants.json. KeyringStore implements the
a2a-go oauth.Store, and the index file's lock is given to the Manager as
its Locker, so refreshes stay serialized across processes. Without a
keychain, or when a token is too large for it, saving a grant fails
instead of writing tokens to disk.

The refresh token is written first, so a rotated one is kept even when
the access token can't be written; the previous access token is then
removed, so the grant is refreshed when next used instead of pairing the
new refresh token with the old access token. A grant the index doesn't
hold yet leaves no keychain entries behind when either write fails,
since auth logout --all would never find them. Like the other OAuth
settings, --oauth-store is not read from a discovered .env, and like
--oauth, an invalid value is a usage error for every command. The README
notes that the keychain keeps tokens off disk but, on macOS, not away
from other processes of the same user, and the size limits of the
macOS and Windows keychains.

List returns the index entries without reading the keychain, with
Refreshable recorded in the index, and Get reads the tokens of the one
grant a caller picked; a missing grant is reported as ErrGrantNotFound.
So auth list, and calls to agents that no stored grant applies to, read
no secrets, and auth logout reads only the tokens it revokes.
@mykytanetipa
mykytanetipa force-pushed the mykytanetipa/sdk-oauth-keychain branch from d73e1ca to ab3b8ca Compare November 15, 2026 14:53
@mykytanetipa

Copy link
Copy Markdown
Author

I traced the grant lifecycle against the a2aclient/oauth manager this builds on, and the design holds together well: Grant.apply only overwrites the refresh token when the server actually rotates it, so the Delete-on-empty arm in KeyringStore.Put only fires for grants that genuinely have no refresh token; forgetAccessToken keeps the refresh token and the store correctly drops just the access entry; and GrantKey.ID() covers issuer/client/resource/scopes but not GrantedScopes, so keychain entry names stay stable across refreshes. The refresh-token-first write ordering is a nice touch for rotation, and the index-file rename (Name) so a FileStore can't mistake a keychain grant for a tokenless file grant is the right call. The TestOAuthFlagsIgnoredFromDiscoveredEnv extension (.env must not choose the store) is a good security-conscious addition too.

One edge the tests don't pin down: when the access-token write fails after the refresh-token write (the ErrSetDataTooBig path in TestKeyringStoreRotatedRefreshToken), the previous access token stays in the keychain, and the next Get pairs it with the new refresh token — a1 + r2 in the test's terms. The test asserts RefreshToken == "r2" but not AccessToken, so either outcome passes. If keeping the stale access token is intended (it's a secret the user already had, and it may still be valid), an explicit AccessToken == "a1" assertion would document that; if not, deleting the access entry before returning the error would make the failure atomic. As-is, a server whose tokens are consistently over the keychain size limit will keep erroring on every refresh and silently keep using the old access token in between.

Minor observation on fill: a hard read error (locked keychain, Secret Service hiccup) on either token aborts the command rather than degrading to a tokenless grant. That's consistent with the no-silent-fallback stance and probably right, just noting the CLI will hard-fail on a locked keychain where --oauth-store file would have kept working.

Good catch, that wasn't intended. Put now drops the old access token when that write fails, so the next use just refreshes, and the test checks for it. Failing hard in fill is on purpose: falling back would only lead to a sign-in whose save fails on the same locked keychain.

@mykytanetipa

Copy link
Copy Markdown
Author

Ran the store tests and the fake-keychain paths (didn't want to test against my real keychain). The refresh-token-first ordering works as described: a failed access-token write during rotation keeps the new refresh token.

If the first save fails partway, say the access token is too big or the keychain write is denied, the refresh token is already in the keychain but the index has no entry. auth logout --all never finds it, so a long-lived token stays behind. The same happens if the index write fails after both keychain writes. Deleting the just-written entries on failure, or writing the index entry first, would cover it.

Also worth noting in the README: on macOS go-keyring caps a secret at about 3 KB after base64, and Windows Credential Manager at 2.5 KB. Entra tokens with group claims can go over that, and you only find out after finishing the browser sign-in.

Agree. Fixed: if the first save fails partway, Put deletes the keychain entries it already wrote. The size limits are in the README now too.

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.

3 participants