Repository navigation
feat(keycardai-oauth): client authentication on credentials - #430
Conversation
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>
1add2b8 to
a80616c
Compare
Release previewkeycardai-oauth 0.35.2 → 0.36.0 (minor)
No other package releases. This comment was automatically generated by the release preview workflow. |
There was a problem hiding this comment.
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_authenticatorrejects it with "WebIdentity client authentication requires client_id".discover_credentialconstructsWebIdentity(server_name=..., storage_dir=...)at credentials.py:975 without the newclient_idoption. It already readsclient_id = env.get("KEYCARD_CLIENT_ID")and passes it to WorkloadIdentity at credentials.py:985. Fix: passclient_id=client_idto 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 theclient_idoption added at credentials.py:213, soself.client_idis None.check_client_authentication()(credentials.py:334) then raises WebIdentityConfigurationError.require_client_authenticator(client_auth.py:66-68) andclient_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_idalso 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 passclient_id. Socheck_client_authentication()raisesWebIdentityConfigurationError("WebIdentity client authentication requires client_id"). Nothing on the base branch breaks, because no code callsclient_authenticationorrequire_client_authenticatorexcept 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>
There was a problem hiding this comment.
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:MultiZoneBasicAuthraisesKeyErrorfor an unknown issuer, and the code turns that intoConfigError, so it fails closed. The single-zone path ignoresissuer.WebIdentity:_signing_client_idprefersresource_client_idand falls back to the newclient_idoption. The assertion is signed withaudset toendpoint, and it raises before signing whenclient_idorendpointis missing.WebIdentityConfigurationErrorsubclasses bothConfigErrorandValueError, so existingexcept ValueErrorcallers still catch it.WorkloadIdentityreturns the token it fetched, plusclient_idwhen 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
left a comment
There was a problem hiding this comment.
Request shapes match base and the credential specs. One small thing inline.
| super().__init__(message, details=details) | ||
|
|
||
|
|
||
| class WebIdentityConfigurationError(ConfigError, ValueError): |
There was a problem hiding this comment.
Every other error in this file derives from OAuthServerError, so except OAuthServerError misses this one. Worth adding it as a base too?
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 aClientAuthenticationwith the headers and form fields that authenticate one request. It never returns a grant parameter.ClientSecretissuer. A multi-zone credential raisesConfigErrorfor a zone it has no credentials for.WebIdentityclient_assertionwithaudset toendpoint, andissandsubset to the newclient_idoption.audience_configdoes not apply.WorkloadIdentityclient_assertion, andclient_idwhen configured.ClientAuthenticatoris a runtime-checkableProtocolseparate fromApplicationCredential, so credentials implemented outside the SDK keep working.require_client_authenticatorraisesConfigErrorfor a credential without it. It also callscheck_client_authentication()when the credential has one.WebIdentity's raises whenclient_idis not set, so a later operation fails before discovery or any request.WebIdentity
client_idToken exchange and
set_client_configuse the auth context'sresource_client_idwhen present, and theclient_idoption otherwise. With neither, both raiseWebIdentityConfigurationError. It is aConfigError, as the spec requires, and also aValueError, so existingexcept ValueErrorblocks still catch it.set_client_configraisedKeyErrorhere before.Spec unit test rows covered
All in
tests/keycardai/oauth/server/test_client_authentication.py.test_client_secret_basic_header,test_client_secret_row_4_unknown_zone_fails_closedtest_web_identity_assertion_for_the_endpoint(verifies the RS256 signature andkidagainst the public key)test_web_identity_client_authentication_misconfigured,test_require_client_authenticator_refusestest_web_identity_row_10_token_exchange_client_idtest_workload_identity_rows_4b_and_4c_form_fieldsaudience_confighas 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:
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, andjust validate-commitspass locally on each branch.🤖 Generated with Claude Code