Skip to content

feat(keycardai-oauth): client authentication on credentials - #430

Merged
cmars merged 2 commits into
casey/eco-486-basic-authfrom
casey/eco-486-client-auth
Nov 17, 2026
Merged

cmars merged 2 commits into
casey/eco-486-basic-authfrom
casey/eco-486-client-auth

Conversation

@cmars

@cmars cmars commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Adds the client-authentication operation from the base spec's Credential operations section. Refresh with a credential (#431) and the device grant (#432, #433) use it. Linear: ECO-486.

client_authentication(issuer=, endpoint=) returns a ClientAuthentication with the headers and form fields that authenticate one request. It never returns a grant parameter.

Credential Returns
ClientSecret The Basic header for the zone named by issuer. A multi-zone credential raises ConfigError for a zone it has no credentials for.
WebIdentity A newly signed client_assertion with aud set to endpoint, and iss and sub set to the new client_id option. audience_config does not apply.
WorkloadIdentity The source's token as client_assertion, and client_id when configured.

ClientAuthenticator is a runtime-checkable Protocol separate from ApplicationCredential, so credentials implemented outside the SDK keep working. require_client_authenticator raises ConfigError for a credential without it. It also calls check_client_authentication() when the credential has one. WebIdentity's raises when client_id is not set, so a later operation fails before discovery or any request.

WebIdentity client_id

Token exchange and set_client_config use the auth context's resource_client_id when present, and the client_id option otherwise. With neither, both raise WebIdentityConfigurationError. It is a ConfigError, as the spec requires, and also a ValueError, so existing except ValueError blocks still catch it. set_client_config raised KeyError here before.

Spec unit test rows covered

All in tests/keycardai/oauth/server/test_client_authentication.py.

Spec Rows Test
ClientSecret 4, 7, 8 test_client_secret_basic_header, test_client_secret_row_4_unknown_zone_fails_closed
WebIdentity 7, 9 test_web_identity_assertion_for_the_endpoint (verifies the RS256 signature and kid against the public key)
WebIdentity 8 test_web_identity_client_authentication_misconfigured, test_require_client_authenticator_refuses
WebIdentity 10 test_web_identity_row_10_token_exchange_client_id
Workload Identity 4b, 4c test_workload_identity_rows_4b_and_4c_form_fields

audience_config has no effect on any path in the SDK today, so the row 9 test guards against a future use of it.

Stack

Replaces #427. Merge in order:

  1. fix(keycardai-oauth): percent-encode the client ID and secret in HTTP Basic #429
  2. feat(keycardai-oauth): client authentication on credentials #430 (this PR)
  3. feat(keycardai-oauth): refresh with a credential #431
  4. feat(keycardai-oauth): device authorization request and single poll #432
  5. feat(keycardai-oauth): poll until done for the device grant #433

The PR workflow runs only on pull requests to main, so #430 to #433 show no CI until their base merges. just check, just typecheck, just test-coverage, just test-release-tooling, and just validate-commits pass locally on each branch.

🤖 Generated with Claude Code

Adds the client-authentication operation from the base spec's
Credential operations section. ClientSecret, WebIdentity, and
WorkloadIdentity implement ClientAuthenticator:

- client_authentication(issuer=, endpoint=) returns a
  ClientAuthentication with the headers and form fields that
  authenticate one request. It never includes a grant parameter.
- ClientSecret returns the Basic header for the issuer's zone. A
  multi-zone credential raises KeyError for an unknown zone.
- WebIdentity signs a new assertion per call, with aud set to the
  endpoint and iss and sub set to the new client_id option.
  audience_config does not apply. Without client_id it raises
  ConfigError.
- WorkloadIdentity returns the source's token, and client_id when
  configured.

ClientAuthenticator is a runtime-checkable Protocol separate from
ApplicationCredential, so credentials implemented outside the SDK keep
working. require_client_authenticator raises ConfigError for a
credential without it.

WebIdentity token exchange and set_client_config use the auth
context's resource_client_id when present, and the client_id option
otherwise.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@cmars
cmars force-pushed the casey/eco-486-client-auth branch from 1add2b8 to a80616c Compare November 16, 2026 23:07
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Release preview

keycardai-oauth 0.35.2 → 0.36.0 (minor)

  • fix(keycardai-oauth): ClientAuthentication repr leaves out its secrets
  • headers and form_fields hold a Basic header or a client assertion.
    repr() printed both, so a traceback that captures locals showed the
    client secret. Both fields now use field(repr=False).
  • feat(keycardai-oauth): client authentication on credentials
  • Adds the client-authentication operation from the base spec's
    Credential operations section. ClientSecret, WebIdentity, and
    WorkloadIdentity implement ClientAuthenticator:
    • client_authentication(issuer=, endpoint=) returns a
      ClientAuthentication with the headers and form fields that
      authenticate one request. It never includes a grant parameter.
  • ClientSecret returns the Basic header for the issuer's zone. A
    multi-zone credential raises KeyError for an unknown zone.
  • WebIdentity signs a new assertion per call, with aud set to the
    endpoint and iss and sub set to the new client_id option.
    audience_config does not apply. Without client_id it raises
    ConfigError.
  • WorkloadIdentity returns the source's token, and client_id when
    configured.
  • ClientAuthenticator is a runtime-checkable Protocol separate from
    ApplicationCredential, so credentials implemented outside the SDK keep
    working. require_client_authenticator raises ConfigError for a
    credential without it.
  • WebIdentity token exchange and set_client_config use the auth
    context's resource_client_id when present, and the client_id option
    otherwise.
  • fix(keycardai-oauth): percent-encode the client ID and secret in HTTP Basic
  • RFC 6749 Section 2.3.1 requires the client ID and secret to be encoded
    before they go into the HTTP Basic credential. BasicAuth.apply_headers
    encodes each one with urllib.parse.quote(value, safe=""). A space
    becomes %20, which form decoders and decodeURIComponent both read as a
    space.
  • Keycard zones percent-decode each half (svc-sts
    packages/w3/src/auth/basic.js), so a client ID with a colon or a secret
    with a percent sign now authenticates. A server that does not decode
    the Basic credential rejects a client ID or secret with a character
    outside A-Z a-z 0-9 - . _ ~.
  • Every Basic header in the SDK comes from BasicAuth, including
    MultiZoneBasicAuth, ClientSecret, and the PKCE helpers.
  • Follows typescript-sdk bump: keycardai-oauth → 0.32.0 #338 and go-sdk docs(mcp,mcp-fastmcp): add hello world server examples #59. ECO-486.

No other package releases.


This comment was automatically generated by the release preview workflow.

@cmars
cmars marked this pull request as ready for review November 16, 2026 23:14

@claude claude Bot 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.

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Additional findings (outside the current diff — GitHub can't attach inline comments there):

  • 🟡 packages/oauth/src/keycardai/oauth/server/credentials.py — A WebIdentity built from environment variables can never do client authentication, even with KEYCARD_CLIENT_ID set. require_client_authenticator rejects it with "WebIdentity client authentication requires client_id". discover_credential constructs WebIdentity(server_name=..., storage_dir=...) at credentials.py:975 without the new client_id option. It already reads client_id = env.get("KEYCARD_CLIENT_ID") and passes it to WorkloadIdentity at credentials.py:985. Fix: pass client_id=client_id to the discovered WebIdentity and document KEYCARD_CLIENT_ID for web identity in the docstring.

    Why this was flagged

    The trigger is an environment with KEYCARD_WEB_IDENTITY_KEY_STORAGE_DIR and KEYCARD_CLIENT_ID both set, so discover_credential() returns WebIdentity at credentials.py:975-977. That construction never sets the client_id option added at credentials.py:213, so self.client_id is None. check_client_authentication() (credentials.py:334) then raises WebIdentityConfigurationError. require_client_authenticator (client_auth.py:66-68) and client_authentication() therefore always fail for discovered WebIdentity credentials. The refresh and device-grant operations that the PR says will use this capability fail the same way. The token-exchange fallback in _signing_client_id also never gets the env client ID. WorkloadIdentity discovery forwards KEYCARD_CLIENT_ID at credentials.py:985, so only WebIdentity is left out. A deployment configured purely through the environment has no way to enable the new capability without building WebIdentity by hand.

    Verification: credentials.py:899 reads client_id = env.get("KEYCARD_CLIENT_ID") or None, but the WebIdentity branch at 974-977 does not pass client_id. So check_client_authentication() raises WebIdentityConfigurationError("WebIdentity client authentication requires client_id"). Nothing on the base branch breaks, because no code calls client_authentication or require_client_authenticator except the new tests.

headers and form_fields hold a Basic header or a client assertion.
repr() printed both, so a traceback that captures locals showed the
client secret. Both fields now use field(repr=False).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@claude claude Bot 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 reviewed the latest push and found no new bugs; the new commit leaves ClientAuthentication's headers and form fields out of repr(). This adds signing of a new client assertion and a new client_id fallback for token exchange, so a human look at the auth behavior is still worthwhile.

What was reviewed:

  • ClientSecret.client_authentication: MultiZoneBasicAuth raises KeyError for an unknown issuer, and the code turns that into ConfigError, so it fails closed. The single-zone path ignores issuer.
  • WebIdentity: _signing_client_id prefers resource_client_id and falls back to the new client_id option. The assertion is signed with aud set to endpoint, and it raises before signing when client_id or endpoint is missing.
  • WebIdentityConfigurationError subclasses both ConfigError and ValueError, so existing except ValueError callers still catch it. WorkloadIdentity returns the token it fetched, plus client_id when one is set.
Extended reasoning...

The change adds a client-authentication capability: a new client_auth.py module, plus implementations on ClientSecret, WebIdentity and WorkloadIdentity in server/credentials.py, and a new exception type. It touches authentication directly: Basic headers built from client secrets, private_key_jwt assertions signed with chosen iss/sub/aud, and which client_id is signed during token exchange. The behavior change for WebIdentity token exchange, which now falls back to a configured client_id instead of raising, is a design choice a person should confirm. The bug hunt ran until it stopped finding anything new and reported no findings, and the new commit fixed the secret-leaking repr. Auth-sensitive code is not approved automatically.

@Larry-Osakwe Larry-Osakwe left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Request shapes match base and the credential specs. One small thing inline.

super().__init__(message, details=details)


class WebIdentityConfigurationError(ConfigError, ValueError):

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Every other error in this file derives from OAuthServerError, so except OAuthServerError misses this one. Worth adding it as a base too?

@cmars
cmars merged commit 3d3f1bd into main Nov 17, 2026
16 checks passed
@cmars
cmars deleted the casey/eco-486-client-auth branch November 17, 2026 23:32
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