feat: Regional Access Boundary Changes #891

vverman · 2026-01-17T01:31:30Z

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.

…d JWT

…ure.

packages/google-auth-library-nodejs/src/auth/regionalaccessboundary.ts

packages/google-auth-library-nodejs/src/auth/baseexternalclient.ts

nbayati · 2026-01-27T20:57:24Z

packages/google-auth-library-nodejs/src/auth/regionalaccessboundary.ts

+
+const log = makeLog('auth');
+
+// googleapis.com


Suggested change

// googleapis.com

packages/google-auth-library-nodejs/src/auth/regionalaccessboundary.ts

nbayati · 2026-01-27T21:06:07Z

packages/google-auth-library-nodejs/src/auth/regionalaccessboundary.ts

+export interface RegionalAccessBoundaryData {
+  /**
+   * The readable text format of the allowed regional access boundary locations.
+   * This is optional, as it might not be present if no regional access boundary is enforced.


This is not accurate. We can't tell if RAB is enforced or not by the list being present.
Also, in the last iteration of design when we removed no-op, this field is not considered optional anymore either. I believe a valid response would have both, but we mostly care about the encodedLocations as that's the field that'd be present in the header.

Thanks for the catch! I think I missed this while making the changes from the TB -> RAB.

I believe as per the latest confirmation, we now expect both the encoded and the readable locations as part of the response from lookup. So I will make the changes to the comments accordingly.

nbayati · 2026-01-27T21:24:53Z

packages/google-auth-library-nodejs/src/auth/regionalaccessboundary.ts

+  private isGlobalEndpoint(url?: string | URL): boolean {
+    if (!url) {
+      return true;
+    }


The isGlobalEndpoint(url?) method currently accepts an optional URL and defaults to true if it's missing. While this works, it makes the method's contract a bit less explicit.

What do you think about refactoring this to make isGlobalEndpoint's signature stricter by always requiring a URL? The logic for handling a missing URL could be moved up to the caller (maybeTriggerRegionalAccessBoundaryRefresh).

This would make it clearer that isGlobalEndpoint's single responsibility is to check a given URL, and the calling method is responsible for the "default to global" logic when no URL is present.

nbayati · 2026-01-27T21:48:33Z

packages/google-auth-library-nodejs/src/auth/regionalaccessboundary.ts

+      const maxRetryTime = 60 * 1000;
+      let shouldContinue = true;
+
+      while (shouldContinue) {


This library already uses gaxios, which provides a powerful and configurable built-in retry mechanism (including exponential backoff) via its retryConfig. This library already uses gaxios, which provides a powerful and configurable built-in retry mechanism (including exponential backoff) via its retryConfig.

The fetchRegionalAccessBoundary method already enables gaxios retries, and then we're wrapping it here in the custom retry logic. I'd recommend refactoring to remove this while loop. Instead, you can add retry conditions to the retryConfig in fetchRegionalAccessBoundary method to achieve the desired behavior. This would leverage existing gaxios functionality, simplify the code, and align with the library's established patterns for request retries.

nbayati · 2026-01-27T23:45:57Z

packages/google-auth-library-nodejs/src/auth/baseexternalclient.ts

+  async getRequestHeaders(url?: string | URL): Promise<Headers> {
    const accessTokenResponse = await this.getAccessToken();
    const headers = new Headers({
      authorization: `Bearer ${accessTokenResponse.token}`,
    });
+    this.maybeTriggerRegionalAccessBoundaryRefresh(
+      url,
+      accessTokenResponse.token!,
+    );


I noticed two problems with this change.

The caller is not passing the URL to the getRequestHeaders() method, both in this file and in externalAccountAuthorizedUserClient.ts, so url is always going to be null.

Even though this is not a breaking change since we're allowing url parameter to be null, I think we can still make the design better by moving the maybeTriggerRegionalAccessBoundaryRefresh() call to the caller method (requestAsync()). This way the getRequestHeaders() doesn't have to know a url, and it can do only 1 task which is getting the headers without potentially invoking a background fetch. Another benefit is that we can enforce that url is not empty, and update the downstream methods such as regionalAccessBoundaryManager.maybeTriggerRegionalAccessBoundaryRefresh and isGlobalEndpoint to expect a non-null URL as well.

nbayati · 2026-01-28T00:09:57Z

packages/google-auth-library-nodejs/src/auth/baseexternalclient.ts

+        !reAuthRetried
+      ) {
+        this.clearRegionalAccessBoundaryCache();
+        return await this.requestAsync<T>(opts, true);


I think we should have two separate flags for the auth retry, and this one (retryWithoutRAB maybe?). Consider this scenario which the single flag approach would fail to handle:

Initial Call: requestAsync(opts) is called.

First Failure: The request fails with a stale RAB error. The catch block clears the RAB cache and retries
the request, with reAuthRetried set to True.

Second Failure: The retried request (now sent without the x-allowed-locations header) fails, but this time with a 401 Unauthorized error because the access token has just expired.

With a single reAuthRetried flag, this second failure would not be handled because it thinks the token has already been refreshed and the request has been retried with the updated credential, and an error would be thrown.

If we use two flags, we can ensure that we only try once without the allowed location header, and then we attempt a true reAuth.

nbayati · 2026-01-28T00:11:14Z

packages/google-auth-library-nodejs/src/auth/externalAccountAuthorizedUserClient.ts

  }

-  async getRequestHeaders(): Promise<Headers> {
+  async getRequestHeaders(url?: string | URL): Promise<Headers> {


Same concern with the getRequestHeaders method in the baseexternalclient.ts file.

nbayati · 2026-01-28T00:12:02Z

packages/google-auth-library-nodejs/src/auth/externalAccountAuthorizedUserClient.ts

-      response = await this.transporter.request<T>(opts);
+      response = await this.transporter.request<T>(requestOpts);
    } catch (e) {
+      if (


Same concern with reusing the reAuthRetried flag for the two different scenario.

nbayati · 2026-01-28T00:14:00Z

packages/google-auth-library-nodejs/src/auth/externalAccountAuthorizedUserClient.ts

   * @throws {Error} If the URL cannot be constructed for a compatible client.
   */
-  protected async getTrustBoundaryUrl(): Promise<string | null> {
+  public async getRegionalAccessBoundaryUrl(): Promise<string | null> {


Why this method became public?

I made it so for ease of testing the getRegionalAccessBoundaryUrl logic. For ex: in the base external client we have scenarios where we want to test if the right url is returned or error is thrown in case of workload, workforce or a null audience.

nbayati · 2026-01-28T00:37:19Z

packages/google-auth-library-nodejs/src/auth/regionalaccessboundary.ts

+  'https://staging-iamcredentials.sandbox.{universe_domain}/v1/projects/-/serviceAccounts/{service_account_email}/allowedLocations';
+
+export const WORKLOAD_LOOKUP_ENDPOINT =
+  'https://iamcredentials.{universe_domain}/v1/projects/{project_id}/locations/global/workloadIdentityPools/{pool_id}/allowedLocations';


We heard back from the backend team that the TPC won't be supported in the future either, so we don't have to consider universe domains other than GDU in here. Let's hardcode it in the URLs and simplify our logic too.

nbayati · 2026-01-28T01:50:00Z

packages/google-auth-library-nodejs/src/auth/jwtclient.ts

+        this.maybeTriggerRegionalAccessBoundaryRefresh(
+          url ?? undefined,
+          (tokens.access_token ?? tokens.id_token)!,
+        );


IIUC the flow correctly, this block is for requesting an id token, and id tokens are not supported by RAB, so there is no need to trigger a refresh here.

…e requestAsync level. RAB urls now have googleapis as universe domain.

vverman added 3 commits January 14, 2026 15:38

Changes for trust boundaries async refresh and support for self-signe…

7d283f5

…d JWT

Fixed unit tests moved RAB logic out of authclient.

c6c1c7b

Changed getRegionalAccessBoundaryUrl and fixed a self-signed jwt fail…

635bae2

…ure.

vverman requested a review from a team as a code owner January 17, 2026 01:31

vverman assigned sofisl, nbayati and miguelvelezsa Jan 17, 2026

Fixed url for service account RAB lookup.

0cfa454

lsirac requested review from miguelvelezsa, nbayati and sofisl January 22, 2026 01:32

nbayati reviewed Jan 27, 2026

View reviewed changes

packages/google-auth-library-nodejs/src/auth/regionalaccessboundary.ts Outdated Show resolved Hide resolved

nbayati reviewed Jan 27, 2026

View reviewed changes

packages/google-auth-library-nodejs/src/auth/baseexternalclient.ts Outdated Show resolved Hide resolved

nbayati reviewed Jan 27, 2026

View reviewed changes

packages/google-auth-library-nodejs/src/auth/regionalaccessboundary.ts Outdated Show resolved Hide resolved

nbayati reviewed Jan 27, 2026

View reviewed changes

nbayati reviewed Jan 28, 2026

View reviewed changes

Formatting and minor fixes

f40a3e1

vverman force-pushed the trust-boundary-upto-speed branch from 238aed8 to f40a3e1 Compare January 29, 2026 02:12

Stale RAB retry now has its own flag. RAB refresh now triggered at th…

3427c0e

…e requestAsync level. RAB urls now have googleapis as universe domain.

feat: Regional Access Boundary Changes #891

Are you sure you want to change the base?

feat: Regional Access Boundary Changes #891

Uh oh!

Conversation

vverman commented Jan 17, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vverman Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

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!

4 participants

vverman Jan 28, 2026 •

edited

Loading