Skip to content

feat(keycardai-oauth): code exchange with a credential - #438

Merged
briankassouf merged 1 commit into
mainfrom
bk/worklaod-identity-client-id
Nov 19, 2026
Merged

briankassouf merged 1 commit into
mainfrom
bk/worklaod-identity-client-id

Conversation

@briankassouf

@briankassouf briankassouf commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

adds the credential option to the authorization-code exchange (Authorization
Code with PKCE, spec-version 6), shaped like refresh with a credential (#431).
A confidential client can authenticate the code exchange with a credential's
client authentication (#430) in place of a client secret, such as a keyless
WorkloadIdentity whose client_id names a v2 token credential.

Changes

  • AsyncClient.exchange_authorization_code(credential=...) calls the
    credential's client authentication with the token endpoint. Its headers and
    form fields go on the request in place of the client's auth strategy and the
    body client_id.
  • complete_authorization(credential=...): client_id is optional and
    required only without credential.
  • authenticate(credential=...): client_id goes on the authorize URL only;
    the code exchange authenticates with the credential.
  • credential together with client_id (or client_secret on
    complete_authorization and authenticate), or a credential without client
    authentication, raises ConfigError before any request. A credential's own
    error propagates as is, with no token request sent.
  • The credential must authenticate as the client_id on the authorize URL.
    The SDK does not compare them; the zone rejects a mismatch with
    invalid_grant.
  • WorkloadIdentity and discover_credential docstrings describe v1 and v2
    token credentials: v2 is resolved by client_id and requires it, v1
    (deprecated) is resolved by the assertion's issuer and subject and rejects
    it. Interactive grants need v2.
  • README: authenticating the web-app code exchange with a credential.

The sync Client does not take a credential, because credentials are async only.

Testing

Unit rows 17 to 22 of the authorization-code-pkce spec, in pkce/test_web.py,
run through a real AsyncClient and check the request on the wire:

  • 17: the body has the code-exchange fields and the credential's fields; the
    headers are the credential's; no subject_token_type
  • 18: credential with client_id or client_secret, or a credential without
    client authentication, is a ConfigError before any request
  • 19, 22: begin with a WorkloadIdentity's client_id, then complete with
    that credential; the authorize URL has the client_id and no assertion, and
    the token request has the same client_id with the assertion and no Basic
    header
  • 20: a WebIdentity assertion has aud set to the token endpoint
  • 21: a failing credential's error is returned as is, and no request is sent

pkce/test_client.py covers authenticate with a credential and its
ConfigError cases.

@briankassouf briankassouf changed the title feat(oauth): workload identity client_id on client credentials and co… feat(oauth): workload identity client_id on client credentials and code exchange Nov 18, 2026

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

redirect_uri=redirect_uri,
code_verifier=pkce.code_verifier,
client_id=client_id,
client_id=None if authenticator is not None else client_id,

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟡 (optional) CLI users who pass client_id plus a WorkloadIdentity with no client_id finish the browser login, then the token exchange fails. At line 195, client_id=None if authenticator is not None else client_id drops the caller's id. That WorkloadIdentity sends only client_assertion, so the zone gets no client_id. It resolves the request as a v1 credential, which cannot do the authorization-code grant. Fix: catch this before the browser opens. Raise ConfigError when the credential has no client_id or a different one (getattr(credential, "client_id", None)), or send the caller's client_id when the credential's form fields leave it out.

Why this was flagged

Trigger: authenticate(client_id="acr_123", issuer=..., credential=WorkloadIdentity(FileTokenSource())), or a credential from discover_credential() when KEYCARD_CLIENT_ID is unset (credentials.py:901). require_client_authenticator (client_auth.py) accepts it because WorkloadIdentity has no check_client_authentication. The flow builds the authorize URL with acr_123, opens the browser and waits for the code (pkce/client.py:171-187). Then line 195 passes client_id=None. WorkloadIdentity.client_authentication (credentials.py:695-701) adds client_id only when self.client_id is set. The zone rejects the exchange only after the user has finished the interactive login. On the base branch there is no credential path, so this is new behaviour. No guard prevents it: the only pre-flight check is credential+client_secret exclusivity at lines 135-141.

Verification: Trigger: a caller passes client_id together with a WorkloadIdentity that has no client_id of its own. require_client_authenticator (client_auth.py:65-72) accepts the credential. pkce/client.py:195 sends client_id=None if authenticator is not None else client_id, so the caller's id is dropped. WorkloadIdentity.client_authentication (credentials.py:695-701) adds client_id only if self.client_id.

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

Matches rows 17 to 22, and the pkce tests ran green for me. One thing before merge: the title needs the full package scope, feat(keycardai-oauth):, or cz won't cut a release. release-preview says nothing to release right now. Python already sends client_id on client credentials, so something like "feat(keycardai-oauth): code exchange with a credential" fits what's here.

@briankassouf briankassouf changed the title feat(oauth): workload identity client_id on client credentials and code exchange feat(keycardai-oauth): workload identity client_id on client credentials and code exchange Nov 19, 2026
@briankassouf briankassouf changed the title feat(keycardai-oauth): workload identity client_id on client credentials and code exchange feat(keycardai-oauth): code exchange with a credential Nov 19, 2026
@briankassouf
briankassouf merged commit 564bf28 into main Nov 19, 2026
16 checks passed
@briankassouf
briankassouf deleted the bk/worklaod-identity-client-id branch November 19, 2026 00:35
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