feat: Async Refresh for Regional Access Boundaries by vverman · Pull Request #1880 · googleapis/google-auth-library-java

vverman · 2026-01-25T21:35:27Z

Contains changes for the feature Regional Access Boundary (Previously Called Trust Boundaries).

The following are salient changes:

Calls to refresh RAB are now all async and in a separate thread.
Logic for refreshing RAB now exists in its own class for cleaner maintenance.
Self-signed jwts are within scope.
Changes to how we trigger RAB refresh and deal with refresh errors.

…pe. Updated tests.

…rors are now retryable.

oauth2_http/java/com/google/auth/http/HttpCredentialsAdapter.java

oauth2_http/java/com/google/auth/oauth2/GoogleCredentials.java

oauth2_http/java/com/google/auth/oauth2/RABManager.java

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundaryManager.java

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundary.java

oauth2_http/java/com/google/auth/oauth2/GoogleCredentials.java

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundaryManager.java

…nce.

oauth2_http/java/com/google/auth/oauth2/ImpersonatedCredentials.java

oauth2_http/java/com/google/auth/oauth2/OAuth2Utils.java

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundaryProvider.java

oauth2_http/java/com/google/auth/http/HttpCredentialsAdapter.java

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundaryManager.java

lqiu96 · 2026-02-10T21:51:06Z

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundary.java

@@ -193,33 +228,41 @@ static TrustBoundary refresh(
            .setInitialIntervalMillis(OAuth2Utils.INITIAL_RETRY_INTERVAL_MILLIS)
            .setRandomizationFactor(OAuth2Utils.RETRY_RANDOMIZATION_FACTOR)
            .setMultiplier(OAuth2Utils.RETRY_MULTIPLIER)
+            .setMaxElapsedTimeMillis(maxRetryElapsedTimeMillis)
            .build();

    HttpUnsuccessfulResponseHandler unsuccessfulResponseHandler =
-        new HttpBackOffUnsuccessfulResponseHandler(backoff);
+        new HttpBackOffUnsuccessfulResponseHandler(backoff)
+            .setBackOffRequired(
+                response -> {
+                  int statusCode = response.getStatusCode();
+                  return statusCode == 500
+                      || statusCode == 502
+                      || statusCode == 503
+                      || statusCode == 504;
+                });


qq, since the server-side will still make the RAB call if we have failure (e.g. no header is attached), can we have this call not have any retries and max duration of like 1-2s?

The reason I'm thinking this way is that the async RAB call uses ForkJoinPool's commonPool. I think we should try to time bound the IO requests that go to that executor pool since that is a JDK executor pool that is shared with the customer's application.

Yes, while requests will succeed without the RAB header, they are expected to encounter significant latency, hence we retry only on transient server errors which are expected to be short lived.

We'd like to ensure that there are as few requests as possible that go without the x-allowed-locations header.

oauth2_http/java/com/google/auth/oauth2/GoogleCredentials.java

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundary.java

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundaryManager.java

oauth2_http/java/com/google/auth/oauth2/ServiceAccountCredentials.java

oauth2_http/java/com/google/auth/oauth2/GoogleCredentials.java

lqiu96 · 2026-02-10T22:12:57Z

Thanks for the clarification @vverman! Would it be possible to split the stable RAB + seeding logic into a separate PR?

…nted. Nit fixes.

nbayati · 2026-02-26T18:50:39Z

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundary.java

+  public static final String X_ALLOWED_LOCATIONS_HEADER_KEY = "x-allowed-locations";
+  private static final long serialVersionUID = -2428522338274020302L;
+
+  static final String ENABLE_EXPERIMENT_ENV_VAR = "GOOGLE_AUTH_TRUST_BOUNDARY_ENABLE_EXPERIMENT";


I think we can remove the env var altogether since this is going to a feature branch and we don't need the feature gate for the release.

That makes sense, I will leave this comment open and make the change once the logic is good to go.

nbayati · 2026-02-26T20:00:23Z

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundary.java

-   * Checks if the trust boundary feature is enabled based on an environment variable. The feature
-   * is enabled if the environment variable is set to "true" or "1" (case-insensitive). Any other
-   * value, or if the variable is unset, will result in the feature being disabled.
+   * Checks if the regional access boundary feature is enabled. The feature is enabled if the


Similar to my other comment, I think we can remove this method along with all env var related code, as they shouldn't be present in the final code being merged to main.

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundary.java

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundaryManager.java

oauth2_http/java/com/google/auth/oauth2/ServiceAccountCredentials.java

oauth2_http/java/com/google/auth/oauth2/GoogleCredentials.java

…now considers expiryTime as opposed to start time. Minor fixes.

…case of async token refresh) or instantiate a new thread.

lqiu96 · 2026-03-09T18:34:09Z

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundaryManager.java

+      if (executor != null) {
+        executor.execute(refreshTask);
+      } else {
+        Thread refreshThread = new Thread(refreshTask, "RAB-refresh-thread");
+        refreshThread.setDaemon(true);
+        refreshThread.start();
+      }


Can you add a comment about this that explains our decisions for this? I think would make sense given the context and constraints we have but may not be super clear to someone reading without knowing our discussions.

e.g. RAB refresh is async and ensured to be at most once 6 hours... intend for this to not block the commonPool if we use completeableAsync, etc.

lqiu96 · 2026-03-09T18:35:09Z

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundaryManager.java

+    // Atomically check if a refresh is already running. If compareAndSet returns true,
+    // this thread "won the race" and is responsible for starting the background task.
+    // All other concurrent threads will return false and exit immediately.
+    if (refreshFuture.compareAndSet(null, future)) {


qq, can you remind me again if we can just set tthe refresh future just be an atomic boolean? Is there a need for it to be a CompletableFuture?

lqiu96 · 2026-03-09T18:38:43Z

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundaryManager.java

+              clock.currentTimeMillis() + INITIAL_COOLDOWN_MILLIS, INITIAL_COOLDOWN_MILLIS);
+    } else {
+      long nextDuration = Math.min(current.durationMillis * 2, MAX_COOLDOWN_MILLIS);
+      next = new CooldownState(clock.currentTimeMillis() + nextDuration, nextDuration);


qq, do we want the next cooldown duration to be from when the call was made or from when the previous cooldown was expired?

e.g.
Call 1 - Time: 0min, cooldown 15 min (error)
Call 2 - Time 30min, cooldown 30 min (error)

I believe this would set the cooldown time to be at 1h. Should be 1hr or 45 min?

lqiu96 · 2026-03-09T18:43:54Z

oauth2_http/java/com/google/auth/oauth2/ServiceAccountCredentials.java

+    List<String> authHeaders = requestMetadata.get(AuthHttpConstants.AUTHORIZATION);
+    if (authHeaders != null && !authHeaders.isEmpty()) {
+      // Extract the token value to trigger a background Regional Access Boundary refresh.
+      String authHeader = authHeaders.get(0);
+      if (authHeader.startsWith(AuthHttpConstants.BEARER + " ")) {
+        String tokenValue = authHeader.substring((AuthHttpConstants.BEARER + " ").length());
+        // Use a null expiration as JWTs are short-lived anyway.
+        AccessToken wrappedToken = new AccessToken(tokenValue, null);
+        // Self-signed JWT do not go through the typical OAuth2Credentials.getRequestMetadata()
+        // flow.
+        // We explicitly trigger it here to ensure the RAB cache is populated/maintained.
+        refreshRegionalAccessBoundaryIfExpired(uri, wrappedToken, null);
+      }


nit: Can we move this logic to a helper? This would be specifcally for SSJWT

Added async logic for RAB refresh/ Now self-signed JWT are in RAB sco…

1b160a8

…pe. Updated tests.

vverman requested review from a team January 25, 2026 21:35

product-auto-label bot added the size: xl Pull request size is extra large. label Jan 25, 2026

Lint fixes.

525ae6d

vverman requested review from lqiu96 and nbayati January 25, 2026 21:49

Url for RAB to include only GDU. Only 500, 502, 503 and 504 lookup er…

b7058ea

…rors are now retryable.

lqiu96 changed the base branch from feat-tb-sa to feat/agentic-identities-cloudrun February 3, 2026 19:16

lqiu96 requested a review from a team as a code owner February 3, 2026 19:16

lqiu96 reviewed Feb 5, 2026

View reviewed changes

oauth2_http/java/com/google/auth/http/HttpCredentialsAdapter.java Outdated Show resolved Hide resolved

lqiu96 reviewed Feb 5, 2026

View reviewed changes

oauth2_http/java/com/google/auth/http/HttpCredentialsAdapter.java Outdated Show resolved Hide resolved

lqiu96 reviewed Feb 5, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/GoogleCredentials.java Outdated Show resolved Hide resolved

lqiu96 reviewed Feb 5, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/GoogleCredentials.java Outdated Show resolved Hide resolved

lqiu96 reviewed Feb 5, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/RABManager.java Outdated Show resolved Hide resolved

lqiu96 reviewed Feb 6, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundaryManager.java Outdated Show resolved Hide resolved

lqiu96 reviewed Feb 6, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundary.java Outdated Show resolved Hide resolved

lqiu96 reviewed Feb 6, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/GoogleCredentials.java Show resolved Hide resolved

lqiu96 reviewed Feb 6, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/GoogleCredentials.java Outdated Show resolved Hide resolved

lqiu96 reviewed Feb 6, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundaryManager.java Outdated Show resolved Hide resolved

vverman changed the base branch from feat/agentic-identities-cloudrun to feat-tb-sa February 6, 2026 22:40

vverman added 2 commits February 6, 2026 15:28

Addressed some PR comments.

e8832a1

Made cooldown into an AtomicReference removed the synchronized refere…

cf1a5e8

…nce.

lqiu96 reviewed Feb 9, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/ImpersonatedCredentials.java Show resolved Hide resolved

lqiu96 reviewed Feb 9, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/OAuth2Utils.java Show resolved Hide resolved

lqiu96 reviewed Feb 9, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundaryProvider.java Show resolved Hide resolved

nbayati reviewed Feb 10, 2026

View reviewed changes

oauth2_http/java/com/google/auth/http/HttpCredentialsAdapter.java Outdated Show resolved Hide resolved

lqiu96 reviewed Feb 10, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundaryManager.java Outdated Show resolved Hide resolved

lqiu96 reviewed Feb 10, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/GoogleCredentials.java Outdated Show resolved Hide resolved

lqiu96 reviewed Feb 10, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundary.java Outdated Show resolved Hide resolved

lqiu96 reviewed Feb 10, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/RegionalAccessBoundaryManager.java Outdated Show resolved Hide resolved

lqiu96 reviewed Feb 10, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/ServiceAccountCredentials.java Show resolved Hide resolved

lqiu96 reviewed Feb 10, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/GoogleCredentials.java Outdated Show resolved Hide resolved

lqiu96 changed the title ~~feat: Regional Access Boundary Update~~ feat: Async Refresh for Regional Access Boundaries Feb 10, 2026

vverman added 4 commits February 23, 2026 18:17

Exclude user-seeded RAB and stale RAB error handling

a9efafb

Removed the user-seeded and stale RAB errors. Soft-expiry now impleme…

b990d5b

…nted. Nit fixes.

getRAB() made package-private

0dd8351

RAB headers now uses guava.ImmutableMap.

7ecd9f9

vverman requested review from lqiu96 and nbayati February 24, 2026 22:30

nbayati reviewed Feb 26, 2026

View reviewed changes

lqiu96 reviewed Feb 27, 2026

View reviewed changes

oauth2_http/java/com/google/auth/oauth2/GoogleCredentials.java Outdated Show resolved Hide resolved

vverman added 2 commits February 27, 2026 17:53

Self-signed JWT now carry RAB headers, unit test updated. RABManager …

000ec25

…now considers expiryTime as opposed to start time. Minor fixes.

forkJoin.common pool is no longer used -> now using the executor (in …

f919023

…case of async token refresh) or instantiate a new thread.

lqiu96 reviewed Mar 9, 2026

View reviewed changes

Removed Env variables gating RAB.

baa4418

vverman requested a review from nbayati March 9, 2026 20:07

Test fix to account for RAB refresh.

52f786f

Conversation

vverman commented Jan 25, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lqiu96 commented Feb 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants