Skip to content

feat: Regional Access Boundary Changes #891

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vverman wants to merge 12 commits into
base: trust_boundary
Choose a base branch
from
Open

feat: Regional Access Boundary Changes #891

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
7d283f5
Changes for trust boundaries async refresh and support for self-signe…
vverman Jan 14, 2026
c6c1c7b
Fixed unit tests moved RAB logic out of authclient.
vverman Jan 17, 2026
635bae2
Changed getRegionalAccessBoundaryUrl and fixed a self-signed jwt fail…
vverman Jan 17, 2026
0cfa454
Fixed url for service account RAB lookup.
vverman Jan 20, 2026
f40a3e1
Formatting and minor fixes
vverman Jan 28, 2026
3427c0e
Stale RAB retry now has its own flag. RAB refresh now triggered at th…
vverman Jan 29, 2026
1bf531a
A special flow where ID tokens were being used in jwtClient too have …
vverman Jan 30, 2026
2856d2f
vanilla fix
vverman Jan 30, 2026
2b247d4
Changed retry codes to remove the 403 and 404. The 500, 502, 503 and …
vverman Jan 30, 2026
27fd517
removed user seeded RAB and stale RAB changes.
vverman Feb 18, 2026
a68acd6
feat: implement RAB soft expiry logic
vverman Feb 20, 2026
eaf0790
Added some comment nit changes
vverman Feb 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 55 additions & 103 deletions packages/google-auth-library-nodejs/src/auth/authclient.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,10 @@ import {log as makeLog} from 'google-logging-utils';

import {PRODUCT_NAME, USER_AGENT} from '../shared.cjs';
import {
isTrustBoundaryEnabled,
NoOpEncodedLocations,
TrustBoundaryData,
} from './trustboundary';
isRegionalAccessBoundaryEnabled,
RegionalAccessBoundaryData,
RegionalAccessBoundaryManager,
} from './regionalaccessboundary';

/**
* An interface for enforcing `fetch`-type compliance.
Expand Down Expand Up @@ -237,8 +237,8 @@ export abstract class AuthClient
eagerRefreshThresholdMillis = DEFAULT_EAGER_REFRESH_THRESHOLD_MILLIS;
forceRefreshOnFailure = false;
universeDomain = DEFAULT_UNIVERSE;
trustBoundaryEnabled: boolean;
trustBoundary?: TrustBoundaryData | null;
regionalAccessBoundaryEnabled: boolean;
protected regionalAccessBoundaryManager: RegionalAccessBoundaryManager;

/**
* Symbols that can be added to GaxiosOptions to specify the method name that is
Expand All @@ -261,12 +261,17 @@ export abstract class AuthClient
this.quotaProjectId = options.get('quota_project_id');
this.credentials = options.get('credentials') ?? {};
this.universeDomain = options.get('universe_domain') ?? DEFAULT_UNIVERSE;
this.trustBoundaryEnabled = isTrustBoundaryEnabled();
this.trustBoundary = null;
this.regionalAccessBoundaryEnabled = isRegionalAccessBoundaryEnabled();

// Shared client options
this.transporter = opts.transporter ?? new Gaxios(opts.transporterOptions);

this.regionalAccessBoundaryManager = new RegionalAccessBoundaryManager({
transporter: this.transporter,
getLookupUrl: async () => this.getRegionalAccessBoundaryUrl(),
isUniverseDomainDefault: () => this.universeDomain === DEFAULT_UNIVERSE,
});

if (options.get('useAuthRequestParameters') !== false) {
this.transporter.interceptors.request.add(
AuthClient.DEFAULT_REQUEST_INTERCEPTOR,
Expand Down Expand Up @@ -371,14 +376,15 @@ export abstract class AuthClient
}>;

/**
* Constructs the trust boundary lookup URL for the client.
* Constructs the regional access boundary lookup URL for the client.
*
* @return The trust boundary URL string, or `null` if the client type
* does not support trust boundaries.
* @return The regional access boundary URL string, or `null` if the client type
* does not support regional access boundaries.
* @throws {Error} If the URL cannot be constructed for a compatible client,
* for instance, if a required property like a service account email is missing.
* @internal
*/
protected async getTrustBoundaryUrl(): Promise<string | null> {
public async getRegionalAccessBoundaryUrl(): Promise<string | null> {
return null;
}

Expand All @@ -389,6 +395,22 @@ export abstract class AuthClient
this.credentials = credentials;
}

/**
* Returns the current regional access boundary data.
* @internal
*/
getRegionalAccessBoundary(): RegionalAccessBoundaryData | null {
return this.regionalAccessBoundaryManager.data;
}

/**
* Returns the current regional access boundary cooldown time in milliseconds.
* @internal
*/
getRegionalAccessBoundaryCooldownTime(): number {
return this.regionalAccessBoundaryManager.cooldownTime;
}

/**
* Append additional headers, e.g., x-goog-user-project, shared across the
* classes inheriting AuthClient. This method should be used by any method
Expand All @@ -408,17 +430,28 @@ export abstract class AuthClient
headers.set('x-goog-user-project', this.quotaProjectId);
}

if (this.trustBoundaryEnabled && this.trustBoundary) {
//Empty header sent in case trust-boundary has no-op encoded location.
headers.set(
'x-allowed-locations',
this.trustBoundary.encodedLocations === NoOpEncodedLocations
? ''
: this.trustBoundary.encodedLocations,
return headers;
}

/**
* Applies regional access boundary rules to the provided headers.
* This includes adding the x-allowed-locations header and triggering
* a background refresh if needed.
* @param headers The headers to update.
* @param url Optional destination URL of the request. If missing, assumed global.
*/
protected applyRegionalAccessBoundary(
headers: Headers,
url?: string | URL,
): void {
const rabHeader =
this.regionalAccessBoundaryManager.getRegionalAccessBoundaryHeader(
url,
headers,
);
if (rabHeader) {
headers.set('x-allowed-locations', rabHeader);
}

return headers;
}

/**
Expand Down Expand Up @@ -446,7 +479,7 @@ export abstract class AuthClient
target.set('authorization', authorizationHeader);
}

if (xGoogAllowedLocs || xGoogAllowedLocs === '') {
if (xGoogAllowedLocs) {
target.set('x-allowed-locations', xGoogAllowedLocs);
}

Expand Down Expand Up @@ -588,87 +621,6 @@ export abstract class AuthClient
};
}

/**
* Refreshes trust boundary data for an authenticated client.
* Handles caching checks and potential fallbacks.
* @param tokens The refreshed credentials containing access token to call the trust boundary endpoint.
* @returns A Promise resolving to TrustBoundaryData or empty-string for no-op trust boundaries.
* @throws {Error} If the request fails and there is no cache available.
*/
protected async refreshTrustBoundary(
tokens: Credentials,
): Promise<TrustBoundaryData | null> {
if (!this.trustBoundaryEnabled) {
return null;
}

if (this.universeDomain !== DEFAULT_UNIVERSE) {
// Skipping check for non-default universe domain as this feature is only supported in GDU
return null;
}

const cachedTB = this.trustBoundary;
if (cachedTB && cachedTB.encodedLocations === NoOpEncodedLocations) {
return cachedTB;
}

const trustBoundaryUrl = await this.getTrustBoundaryUrl();
if (!trustBoundaryUrl) {
return null;
}

const accessToken = tokens.access_token;

if (!accessToken || this.isExpired(tokens)) {
throw new Error(
'TrustBoundary: Error calling lookup endpoint without valid access token',
);
}

const headers = this.addSharedMetadataHeaders(
new Headers({
//we can directly pass the access_token as the trust boundaries are always fetched after token refresh
authorization: 'Bearer ' + accessToken,
}),
);

const opts: GaxiosOptions = {
...{
retry: true,
retryConfig: {
httpMethodsToRetry: ['GET'],
},
},
headers,
url: trustBoundaryUrl,
};

try {
const {data: trustBoundaryData} =
// Use the transporter directly here. A standard `client.request` would
// re-trigger a token refresh, creating an infinite loop.
await this.transporter.request<TrustBoundaryData>(opts);

if (!trustBoundaryData.encodedLocations) {
throw new Error(
'TrustBoundary: Malformed response from lookup endpoint.',
);
}

return trustBoundaryData;
} catch (error) {
if (this.trustBoundary) {
return this.trustBoundary; // return cached tb if call to lookup fails
}
throw new Error(
'TrustBoundary: Failure while getting trust boundaries:',
{
cause: error,
},
);
}
}

/**
* Returns whether the provided credentials are expired or will expire within
* eagerRefreshThresholdMillismilliseconds.
Expand Down
43 changes: 23 additions & 20 deletions packages/google-auth-library-nodejs/src/auth/baseexternalclient.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ import {
SERVICE_ACCOUNT_LOOKUP_ENDPOINT,
WORKFORCE_LOOKUP_ENDPOINT,
WORKLOAD_LOOKUP_ENDPOINT,
} from './trustboundary';
} from './regionalaccessboundary';

/**
* The required token exchange grant_type: rfc8693#section-2.1
Expand Down Expand Up @@ -424,11 +424,12 @@ export abstract class BaseExternalAccountClient extends AuthClient {
* The result has the form:
* { authorization: 'Bearer <access_token_value>' }
*/
async getRequestHeaders(): Promise<Headers> {
async getRequestHeaders(url?: string | URL): Promise<Headers> {
const accessTokenResponse = await this.getAccessToken();
const headers = new Headers({
authorization: `Bearer ${accessTokenResponse.token}`,
});
this.applyRegionalAccessBoundary(headers, url);
return this.addSharedMetadataHeaders(headers);
}

Expand Down Expand Up @@ -500,20 +501,22 @@ export abstract class BaseExternalAccountClient extends AuthClient {
* returned response.
* @param opts The HTTP request options.
* @param reAuthRetried Whether the current attempt is a retry after a failed attempt due to an auth failure.
* @param retryWithoutRAB Whether the current attempt is a retry after a failed attempt due to a stale regional access boundary.
Copy link

@nbayati nbayati Feb 21, 2026

Choose a reason for hiding this comment

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

Unused parameter: Since we no longer have the reactive refresh in this PR, this parameter should be removed too.

* @return A promise that resolves with the successful response.
*/
protected async requestAsync<T>(
opts: GaxiosOptions,
reAuthRetried = false,
): Promise<GaxiosResponse<T>> {
let response: GaxiosResponse;
const requestOpts = {...opts};
try {
const requestHeaders = await this.getRequestHeaders();
opts.headers = Gaxios.mergeHeaders(opts.headers);
const requestHeaders = await this.getRequestHeaders(opts.url);
requestOpts.headers = Gaxios.mergeHeaders(requestOpts.headers);

this.applyHeadersFromSource(opts.headers, requestHeaders);
this.applyHeadersFromSource(requestOpts.headers, requestHeaders);

response = await this.transporter.request<T>(opts);
response = await this.transporter.request<T>(requestOpts);
} catch (e) {
const res = (e as GaxiosError).response;
if (res) {
Expand Down Expand Up @@ -624,7 +627,6 @@ export abstract class BaseExternalAccountClient extends AuthClient {
Object.assign(this.credentials, this.cachedAccessToken);
delete (this.credentials as CredentialsWithResponse).res;

this.trustBoundary = await this.refreshTrustBoundary(this.credentials);
// Trigger tokens event to notify external listeners.
this.emit('tokens', {
refresh_token: null,
Expand Down Expand Up @@ -718,42 +720,43 @@ export abstract class BaseExternalAccountClient extends AuthClient {
return this.tokenUrl;
}

protected async getTrustBoundaryUrl(): Promise<string> {
public async getRegionalAccessBoundaryUrl(): Promise<string> {
if (this.serviceAccountImpersonationUrl) {
// When impersonating a service account, the trust boundary is determined
// When impersonating a service account, the regional access boundary is determined
// by the security policies of the target service account.
const email = this.getServiceAccountEmail();
if (!email) {
throw new Error(
`TrustBoundary: A service account email is required for trust boundary lookups but could not be determined from the serviceAccountImpersonationUrl ${this.serviceAccountImpersonationUrl}.`,
`RegionalAccessBoundary: A service account email is required for regional access boundary lookups but could not be determined from the serviceAccountImpersonationUrl ${this.serviceAccountImpersonationUrl}.`,
);
}
return SERVICE_ACCOUNT_LOOKUP_ENDPOINT.replace(
'{universe_domain}',
this.universeDomain,
).replace('{service_account_email}', encodeURIComponent(email));
'{service_account_email}',
encodeURIComponent(email),
);
}

// Check if the audience corresponds to a workload identity pool.
const wfPoolId = getWorkforcePoolIdFromAudience(this.audience);
if (wfPoolId) {
return WORKFORCE_LOOKUP_ENDPOINT.replace(
'{universe_domain}',
this.universeDomain,
).replace('{pool_id}', encodeURIComponent(wfPoolId));
'{pool_id}',
encodeURIComponent(wfPoolId),
);
}

// Check if the audience corresponds to a workforce identity pool.
const wlPoolId = getWorkloadPoolIdFromAudience(this.audience);
const projectNumber = this.getProjectNumber(this.audience);
if (wlPoolId && projectNumber) {
return WORKLOAD_LOOKUP_ENDPOINT.replace('{project_id}', projectNumber)
.replace('{pool_id}', wlPoolId)
.replace('{universe_domain}', this.universeDomain);
return WORKLOAD_LOOKUP_ENDPOINT.replace(
'{project_id}',
projectNumber,
).replace('{pool_id}', wlPoolId);
}

throw new RangeError(
`TrustBoundary: Invalid audience provided: "${this.audience}" does not correspond to a workforce or workload pool.`,
`RegionalAccessBoundary: Invalid audience provided: "${this.audience}" does not correspond to a workforce or workload pool.`,
);
}
}
11 changes: 5 additions & 6 deletions packages/google-auth-library-nodejs/src/auth/computeclient.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ import {
OAuth2Client,
OAuth2ClientOptions,
} from './oauth2client';
import {SERVICE_ACCOUNT_LOOKUP_ENDPOINT} from './trustboundary';
import {SERVICE_ACCOUNT_LOOKUP_ENDPOINT} from './regionalaccessboundary';

export interface ComputeOptions extends OAuth2ClientOptions {
/**
Expand Down Expand Up @@ -90,7 +90,6 @@ export class Compute extends OAuth2Client {
tokens.expiry_date = new Date().getTime() + data.expires_in * 1000;
delete (tokens as CredentialRequest).expires_in;
}
this.trustBoundary = await this.refreshTrustBoundary(data);
this.emit('tokens', tokens);
return {tokens, res: null};
}
Expand Down Expand Up @@ -140,13 +139,13 @@ export class Compute extends OAuth2Client {
}
}

protected async getTrustBoundaryUrl(): Promise<string> {
public async getRegionalAccessBoundaryUrl(): Promise<string> {
const email = await this.resolveServiceAccountEmail();
const trustBoundaryUrl = SERVICE_ACCOUNT_LOOKUP_ENDPOINT.replace(
const regionalAccessBoundaryUrl = SERVICE_ACCOUNT_LOOKUP_ENDPOINT.replace(
'{universe_domain}',
this.universeDomain,
Comment on lines 145 to 146
Copy link

@nbayati nbayati Feb 20, 2026

Choose a reason for hiding this comment

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

SERVICE_ACCOUNT_LOOKUP_ENDPOINT no longer has a placeholder for universedomain.
The tests such as test/test.authclient.ts and test/test.compute.ts should be updated to remove the unnecessary replace too.

).replace('{service_account_email}', encodeURIComponent(email));
return trustBoundaryUrl;
return regionalAccessBoundaryUrl;
}

/**
Expand All @@ -165,7 +164,7 @@ export class Compute extends OAuth2Client {
return await gcpMetadata.instance('service-accounts/default/email');
} catch (e) {
throw new Error(
'TrustBoundary: Failed to retrieve default service account email from metadata server.',
'RegionalAccessBoundary: Failed to retrieve default service account email from metadata server.',
{
cause: e,
},
Expand Down
Loading