fix(auth): include PKCE code_challenge for MCP OAuth flows

[pandego]

Summary

Fixes #4708.

This updates the OAuth authorization flow to include PKCE parameters when requested by MCP tool credentials, so providers that require code_challenge no longer reject the initial auth handshake.

What changed

• Added explicit OAuth2 credential fields for PKCE:
  • code_challenge_method
  • code_verifier
• In auth URI generation:
  • when code_challenge_method is set, ADK now ensures a code_verifier exists,
  • passes PKCE params into create_authorization_url(...).
• In token exchange:
  • passes code_verifier to fetch_token(...) for authorization-code exchange.
• Added unit tests covering:
  • PKCE parameters present in generated auth URL,
  • code_verifier forwarded during token exchange.

Testing plan

• uv run pytest tests/unittests/auth/test_auth_handler.py tests/unittests/auth/exchanger/test_oauth2_credential_exchanger.py

Both test files pass locally.

Checklist

• Linked issue
• Focused, minimal scope
• Unit tests updated for new behavior

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the OAuth authorization flow to support PKCE (Proof Key for Code Exchange), addressing an issue where certain providers rejected initial authentication handshakes due to missing code_challenge parameters. The changes enable the system to correctly generate and utilize PKCE parameters throughout the OAuth process, from authorization URI creation to token exchange, thereby improving compatibility with modern OAuth2 implementations.

Highlights

• PKCE Parameter Support: Added code_challenge_method and code_verifier fields to the OAuth2Auth credential model to support PKCE (Proof Key for Code Exchange) flows.
• Authorization URI Generation: Modified the generate_auth_uri function to automatically generate a code_verifier and include PKCE parameters (code_challenge_method, code_verifier) in the authorization URL when a code_challenge_method is specified.
• Token Exchange Enhancement: Updated the _exchange_authorization_code function to pass the code_verifier during the OAuth2 token exchange, ensuring proper PKCE validation with identity providers.
• Unit Test Coverage: Introduced new unit tests to validate the correct inclusion of PKCE parameters in generated authorization URLs and the proper forwarding of the code_verifier during token exchange.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• src/google/adk/auth/auth_credential.py
  • Added code_challenge_method and code_verifier fields to OAuth2Auth.
• src/google/adk/auth/auth_handler.py
  • Imported secrets module for code_verifier generation.
  • Updated generate_auth_uri to include PKCE parameters and generate code_verifier.
• src/google/adk/auth/exchanger/oauth2_credential_exchanger.py
  • Modified _exchange_authorization_code to pass code_verifier during token exchange.
• tests/unittests/auth/exchanger/test_oauth2_credential_exchanger.py
  • Added test_exchange_authorization_code_with_code_verifier to verify PKCE in token exchange.
• tests/unittests/auth/test_auth_handler.py
  • Updated MockOAuth2Session to handle code_challenge_method in create_authorization_url.
  • Added test_generate_auth_uri_with_pkce to verify PKCE parameters in auth URI generation.

Activity

• The author linked issue MCP tool Oauth handshake error with "code_challenge required" #4708, indicating this PR is a fix for a known problem.
• The changes have a focused, minimal scope, targeting specific OAuth flow enhancements.
• Unit tests were updated to cover the new behavior, ensuring the PKCE implementation works as expected.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request aims to add PKCE support for OAuth flows. While the changes to the data model and the token exchange part are correct, there is a critical issue in the authorization URI generation. The implementation incorrectly passes the code_verifier instead of the required code_challenge. Additionally, the unit tests use a mock that masks this bug, preventing it from being caught. My review includes feedback on fixing the implementation and improving the test mock.

[pandego]

Thanks for the review, addressed in the latest push.

What changed:

• generate_auth_uri now sends code_challenge + code_challenge_method for PKCE auth requests.
• code_challenge is derived from code_verifier (S256 uses Authlib RFC7636 helper).
• code_verifier remains stored on the credential and is only sent during token exchange.
• Test mock was tightened to reflect real behavior and the PKCE test now asserts code_verifier is not present in the authorization URL.

Validation run:

• uv run pytest tests/unittests/auth/test_auth_handler.py tests/unittests/auth/exchanger/test_oauth2_credential_exchanger.py
• 36 passed

[anowardear062-svg]

The best interest way

[anowardear062-svg]

Thanks for the update

[rohityan]

Hi @pandego , Thank you for your contribution! We appreciate you taking the time to submit this pull request. Your PR has been received by the team and is currently under review. We will provide feedback as soon as we have an update to share.

[rohityan]

Hi @wuliang229 , can you please review this.

[pandego]

Rebased this branch onto the latest main and force-pushed 6da89c43.

Validation rerun:

• uv run --extra test pytest tests/unittests/tools/mcp_tool/test_mcp_session_manager.py -q -> 26 passed

There were two pytest teardown runtime warnings from async mocks/exit stack after the suite completed, but the targeted MCP session manager tests passed cleanly.

[rohityan]

Hi @pandego , This PR has merge conflicts that require changes from your end. Could you please rebase your branch with the latest main branch to address these? Once this is complete, please let us know so we can proceed with the review.

[pandego]

Rebased this branch onto the latest main and force-pushed ec4f66e6.

Also folded in the PKCE auth URL fix while resolving the rebase so the authorization request now sends code_challenge/code_challenge_method, keeps code_verifier for the token exchange only, and preserves the existing client_secret_post behavior during token fetch.

Validation rerun:

• uv run --extra test pytest tests/unittests/auth/test_auth_handler.py tests/unittests/auth/exchanger/test_oauth2_credential_exchanger.py
• 37 passed

[pandego]

Rebased this branch onto the latest main and force-pushed 0df1f741.

Validation rerun:

• uv run --extra test pytest tests/unittests/auth/test_auth_handler.py tests/unittests/auth/exchanger/test_oauth2_credential_exchanger.py
• 37 passed

This keeps the PKCE auth URL behavior intact (code_challenge / code_challenge_method on the authorization request, code_verifier only during token exchange). Ready for review again.