Skip to content

feat: implement updated design for regional access boundary#16084

Open
nbayati wants to merge 16 commits intogoogleapis:mainfrom
nbayati:rab-async-redesign
Open

feat: implement updated design for regional access boundary#16084
nbayati wants to merge 16 commits intogoogleapis:mainfrom
nbayati:rab-async-redesign

Conversation

@nbayati
Copy link
Copy Markdown
Contributor

@nbayati nbayati commented Mar 12, 2026

Original PR: googleapis/google-auth-library-python#1955
Make the fetching async and non blocking.
Implement proactive refresh every 6 hours.
Centralize the logic in a new class.
Remove no-op signal and checks.
Refactor to Regional Access Boundary name.

Make the fetching async and non blocking.
Implement proactive refresh every 6 hours.
Centralize the logic in a new class.
Remove no-op signal and checks.
Refactor to Regional Access Boundary name.
@nbayati nbayati requested review from a team as code owners March 12, 2026 01:16
@gemini-code-assist
Copy link
Copy Markdown
Contributor

Summary of Changes

Hello, I'm Gemini Code Assist1! 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 significantly overhauls the internal handling of regional access boundaries within the authentication library. The primary goal is to enhance the reliability and performance of this feature by introducing an asynchronous, non-blocking data fetching mechanism with proactive background refreshes. This refactoring centralizes the complex logic, streamlines error handling, and sets the stage for more robust regional access control.

Highlights

  • Refactored Regional Access Boundary: The "Trust Boundary" feature has been renamed and refactored to "Regional Access Boundary" for clarity and consistency across the codebase.
  • Asynchronous and Non-Blocking Fetching: The process of fetching Regional Access Boundary information is now asynchronous and non-blocking, improving application responsiveness and preventing UI freezes.
  • Proactive Refresh Mechanism: Regional Access Boundary data is proactively refreshed every 6 hours in the background to ensure up-to-date information without requiring explicit calls.
  • Centralized Logic: All core logic for managing Regional Access Boundaries has been centralized into a new utility module, _regional_access_boundary_utils.py, enhancing maintainability and modularity.
  • Deprecated Parameters and Methods: The trust_boundary parameter and with_trust_boundary methods have been deprecated across various credential types, with warnings issued upon their use to guide developers towards the new design.
  • Simplified Error Handling and Retries: Regional Access Boundary lookup failures now log errors and return None instead of raising exceptions, and HTTP 502 (Bad Gateway) errors are now considered retryable, making the system more resilient.
Changelog
  • packages/google-auth/google/auth/_constants.py
    • Updated endpoint names and removed universe_domain from format strings.
  • packages/google-auth/google/auth/_helpers.py
    • Removed the get_bool_from_env utility function.
  • packages/google-auth/google/auth/_regional_access_boundary_utils.py
    • Added a new module to centralize Regional Access Boundary management logic, including data structures, manager, and refresh thread.
  • packages/google-auth/google/auth/compute_engine/credentials.py
    • Updated to use the new CredentialsWithRegionalAccessBoundary base class.
    • Deprecated trust_boundary parameter.
    • Renamed lookup URL builder.
    • Refined error handling.
  • packages/google-auth/google/auth/credentials.py
    • Replaced CredentialsWithTrustBoundary with CredentialsWithRegionalAccessBoundary.
    • Deprecated with_trust_boundary.
    • Introduced a new _rab_manager for state.
    • Refactored refresh and header application logic.
  • packages/google-auth/google/auth/external_account.py
    • Migrated to CredentialsWithRegionalAccessBoundary.
    • Deprecated trust_boundary parameter.
    • Updated Regional Access Boundary lookup URL construction and error handling.
  • packages/google-auth/google/auth/external_account_authorized_user.py
    • Migrated to CredentialsWithRegionalAccessBoundary.
    • Removed trust_boundary parameter.
    • Updated Regional Access Boundary lookup URL construction and error handling.
  • packages/google-auth/google/auth/identity_pool.py
    • Removed the explicit call to handle trust boundary refresh.
  • packages/google-auth/google/auth/impersonated_credentials.py
    • Migrated to CredentialsWithRegionalAccessBoundary.
    • Deprecated trust_boundary parameter.
    • Updated Regional Access Boundary lookup URL construction and error handling.
  • packages/google-auth/google/oauth2/_client.py
    • Renamed trust boundary lookup functions to regional access boundary.
    • Improved error logging.
    • Increased retry attempts.
    • Added HTTP 502 as a retryable status.
  • packages/google-auth/google/oauth2/_service_account_async.py
    • Added before_request overrides to bypass synchronous Regional Access Boundary refresh for async credentials.
  • packages/google-auth/google/oauth2/credentials.py
    • Deprecated the trust_boundary parameter in the constructor.
  • packages/google-auth/google/oauth2/service_account.py
    • Migrated to CredentialsWithRegionalAccessBoundary.
    • Deprecated trust_boundary parameter.
    • Updated Regional Access Boundary lookup URL construction and error handling.
  • packages/google-auth/tests/compute_engine/test_credentials.py
    • Removed deprecated trust boundary tests.
    • Updated regional access boundary lookup URL tests.
  • packages/google-auth/tests/oauth2/test__client.py
    • Renamed and updated tests for regional access boundary lookup, including new error handling and retry logic.
  • packages/google-auth/tests/oauth2/test_service_account.py
    • Removed deprecated trust boundary tests.
    • Added a test for regional access boundary lookup URL.
  • packages/google-auth/tests/test__helpers.py
    • Removed tests for the get_bool_from_env function.
  • packages/google-auth/tests/test__regional_access_boundary_utils.py
    • Added a new test file for the _regional_access_boundary_utils module, covering its core functionalities.
  • packages/google-auth/tests/test_aws.py
    • Removed trust_boundary parameter from from_info and from_file test calls.
  • packages/google-auth/tests/test_credentials.py
    • Updated CredentialsImpl to reflect the new CredentialsWithRegionalAccessBoundary base class and its associated manager.
    • Removed old trust boundary tests.
  • packages/google-auth/tests/test_external_account.py
    • Removed deprecated trust boundary tests.
    • Updated regional access boundary lookup URL tests.
  • packages/google-auth/tests/test_external_account_authorized_user.py
    • Removed deprecated trust boundary tests.
    • Updated regional access boundary lookup URL tests.
  • packages/google-auth/tests/test_identity_pool.py
    • Removed trust_boundary parameter from from_info and from_file test calls.
  • packages/google-auth/tests/test_impersonated_credentials.py
    • Removed deprecated trust boundary tests.
    • Updated regional access boundary lookup URL tests.
  • packages/google-auth/tests/test_pluggable.py
    • Removed trust_boundary parameter from from_info and from_file test calls.
Activity
  • The author, nbayati, opened this pull request with a clear intent to implement an updated design for regional access boundary. The description outlines the key changes: making fetching async and non-blocking, implementing proactive refresh, centralizing logic in a new class, removing no-op signals, and refactoring to the new name. There are no other comments or reviews mentioned in the provided context.
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.

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

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

Code Review

This pull request introduces a significant and well-executed refactoring of the regional access boundary feature. The changes implement a more robust design with non-blocking, asynchronous fetching, proactive refresh, and exponential backoff on failure. The logic has been effectively centralized into new utility classes, and the feature has been consistently renamed from "Trust Boundary" to "Regional Access Boundary" across the codebase. The implementation appears solid and greatly improves the feature's resilience. I have a couple of minor suggestions to modernize the Python syntax for super() calls in the new and modified code.

@nbayati nbayati requested a review from daniel-sanche March 17, 2026 19:58
@lsirac
Copy link
Copy Markdown
Contributor

lsirac commented Mar 19, 2026

Review

  • CredentialsWithTrustBoundary compatibility is still not preserved for external subclasses. Right now CredentialsWithTrustBoundary is only an alias to CredentialsWithRegionalAccessBoundary. The new base class requires _perform_refresh_token() and _build_regional_access_boundary_lookup_url(). So any external subclass that previously inherited CredentialsWithTrustBoundary, implemented refresh(), and implemented _build_trust_boundary_lookup_url() can now fail abstract-class instantiation after upgrade.

  • mock.ANY is still used in the GCE tests. tests/compute_engine/test_credentials.py still uses mock.ANY when asserting the request passed to get_service_account_info(...). We should avoid this where possible. There may be more uses.

  • There is no direct happy-path coverage for the background refresh thread. The new tests mostly mock start_refresh or _lookup_regional_access_boundary, but I don't see a test for _RegionalAccessBoundaryRefreshThread.run() end-to-end and proves the real thread updates expiry/cooldown/header state correctly.

  • Impersonated credentials ignore iam_endpoint_override on the RAB path. Is this intentional?

Test Coverage Gaps

  • We should add a test that subclasses CredentialsWithTrustBoundary, only implements the old abstract methods, and still instantiates/works after upgrade.

  • Test that iam_endpoint_override is honored on the RAB lookup path. I don't see one that checks the RAB lookup URL itself.

  • Test for the refresh thread when cached RAB is expired. The thread code is supposed to clear the cached header after hard expiry if refresh fails.

  • We should have a test proving async creds do not accidentally trigger sync RAB refresh behavior.

  • No test for external-account impersonation delegation behavior. external_account.py forwards RAB refresh responsibility to the impersonated credential when impersonation is in play. We need a test proving we only do one RAB lookup through that path instead of duplicating work.

Copy link
Copy Markdown
Contributor

@daniel-sanche daniel-sanche left a comment

Choose a reason for hiding this comment

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

few small comments and questions, but overall looks good

from google.auth.transport import _http_client

request = google_auth_requests.Request()
request = _http_client.Request()
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.

We're running into issues because _http_client doesn't support mtls. Will that be a problem here?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Good catch! Yeah this would be a problem here. To address both your original concern (optional dependencies) and your follow-up (mTLS support), I’ve applied a try / except ImportError pattern to both _build_regional_access_boundary_lookup_url and universe_domain properties so we can try to import and use requests which for those who are using mTLS must be installed anyway, and fallback to _http_client if it's not installed.

Copy link
Copy Markdown
Contributor

@daniel-sanche daniel-sanche Mar 27, 2026

Choose a reason for hiding this comment

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

requests ... for those who are using mTLS must be installed anyway

Where is this enforced? In #16090 (comment), we're running into an issue where that's not the case

This question is probably outside the scope of this change, but I just want to understand it better

@nbayati
Copy link
Copy Markdown
Contributor Author

nbayati commented Mar 27, 2026

Review

  • CredentialsWithTrustBoundary compatibility is still not preserved for external subclasses. Right now CredentialsWithTrustBoundary is only an alias to CredentialsWithRegionalAccessBoundary. The new base class requires _perform_refresh_token() and _build_regional_access_boundary_lookup_url(). So any external subclass that previously inherited CredentialsWithTrustBoundary, implemented refresh(), and implemented _build_trust_boundary_lookup_url() can now fail abstract-class instantiation after upgrade.
  • mock.ANY is still used in the GCE tests. tests/compute_engine/test_credentials.py still uses mock.ANY when asserting the request passed to get_service_account_info(...). We should avoid this where possible. There may be more uses.
  • There is no direct happy-path coverage for the background refresh thread. The new tests mostly mock start_refresh or _lookup_regional_access_boundary, but I don't see a test for _RegionalAccessBoundaryRefreshThread.run() end-to-end and proves the real thread updates expiry/cooldown/header state correctly.
  • Impersonated credentials ignore iam_endpoint_override on the RAB path. Is this intentional?

Test Coverage Gaps

  • We should add a test that subclasses CredentialsWithTrustBoundary, only implements the old abstract methods, and still instantiates/works after upgrade.
  • Test that iam_endpoint_override is honored on the RAB lookup path. I don't see one that checks the RAB lookup URL itself.
  • Test for the refresh thread when cached RAB is expired. The thread code is supposed to clear the cached header after hard expiry if refresh fails.
  • We should have a test proving async creds do not accidentally trigger sync RAB refresh behavior.
  • No test for external-account impersonation delegation behavior. external_account.py forwards RAB refresh responsibility to the impersonated credential when impersonation is in play. We need a test proving we only do one RAB lookup through that path instead of duplicating work.

Thanks for the review feedback @lsirac
Test coverage and mock.ANY in tests are fixed. I've added back CredentialsWithTrustBoundary as a bridge class so the backward compatibility should be resolved too.

Re iam_endpoint_override, it comes from the service_account_impersonation_url field from the JSON file of the external account, and it's the endpoint we should call to get a token, not necessarily an override for all iam endpoints. However, I realized that we weren't respecting mtls vs non-mtls iam endpoint, so I refactored the code to use the existing iam module to determine the right endpoint!

@nbayati nbayati requested a review from daniel-sanche March 27, 2026 21:30
Copy link
Copy Markdown
Contributor

@daniel-sanche daniel-sanche left a comment

Choose a reason for hiding this comment

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

LGTM

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