Class BaseExternalAccountClient (9.0.0)

Base external account client. This is used to instantiate AuthClients for exchanging external account credentials for GCP access token and authorizing requests to GCP APIs. The base class implements common logic for exchanging various type of external credentials for GCP access token. The logic of determining and retrieving the external credential based on the environment and credential_source will be left for the subclasses.

Inheritance

AuthClient > BaseExternalAccountClient

Package

google-auth-library

Constructors

(constructor)(options, additionalOptions)

constructor(options: BaseExternalAccountClientOptions, additionalOptions?: RefreshOptions);

Instantiate a BaseExternalAccountClient instance using the provided JSON object loaded from an external account credentials file.

Parameters
Name	Description
`options`	`BaseExternalAccountClientOptions` The external account options object typically loaded from the external account JSON credential file.
`additionalOptions`	`RefreshOptions` Optional additional behavior customization options. These currently customize expiration threshold time and whether to retry on 401/403 API request errors.

Properties

audience

protected readonly audience: string;

eagerRefreshThresholdMillis

readonly eagerRefreshThresholdMillis: number;

forceRefreshOnFailure

readonly forceRefreshOnFailure: boolean;

projectId

projectId: string | null;

projectNumber

projectNumber: string | null;

scopes

scopes?: string | string[];

OAuth scopes for the GCP access token to use. When not provided, the default https://www.googleapis.com/auth/cloud-platform is used.

Methods

getAccessToken()

getAccessToken(): Promise<GetAccessTokenResponse>;

A promise that resolves with the current GCP access token response. If the current credential is expired, a new one is retrieved.

Returns
Type	Description
`Promise<GetAccessTokenResponse>`

getProjectId()

getProjectId(): Promise<string | null>;

A promise that resolves with the project ID corresponding to the current workload identity pool or current workforce pool if determinable. For workforce pool credential, it returns the project ID corresponding to the workforcePoolUserProject. This is introduced to match the current pattern of using the Auth library: const projectId = await auth.getProjectId(); const url = https://dns.googleapis.com/dns/v1/projects/${projectId}; const res = await client.request({ url }); The resource may not have permission (resourcemanager.projects.get) to call this API or the required scopes may not be selected: https://cloud.google.com/resource-manager/reference/rest/v1/projects/get#authorization-scopes

Returns
Type	Description
`Promise<string \| null>`

getRequestHeaders()

getRequestHeaders(): Promise<Headers>;

The main authentication interface. It takes an optional url which when present is the endpoint being accessed, and returns a Promise which resolves with authorization header fields.

The result has the form: { Authorization: 'Bearer <access_token_value>' }

Returns
Type	Description
`Promise<Headers>`

getServiceAccountEmail()

getServiceAccountEmail(): string | null;

The service account email to be impersonated, if available.

Returns
Type	Description
`string \| null`

refreshAccessTokenAsync()

protected refreshAccessTokenAsync(): Promise<CredentialsWithResponse>;

Forces token refresh, even if unexpired tokens are currently cached. External credentials are exchanged for GCP access tokens via the token exchange endpoint and other settings provided in the client options object. If the service_account_impersonation_url is provided, an additional step to exchange the external account GCP access token for a service account impersonated token is performed. A promise that resolves with the fresh GCP access tokens.

Returns
Type	Description
`Promise<CredentialsWithResponse>`

request(opts)

request<T>(opts: GaxiosOptions): GaxiosPromise<T>;

Provides a request implementation with OAuth 2.0 flow. In cases of HTTP 401 and 403 responses, it automatically asks for a new access token and replays the unsuccessful request.

Parameter
Name	Description
`opts`	`GaxiosOptions` Request options.

Returns
Type	Description
`GaxiosPromise<T>`

Type Parameter
Name	Description
`T`

request(opts, callback)

request<T>(opts: GaxiosOptions, callback: BodyResponseCallback<T>): void;

Parameters
Name	Description
`opts`	`GaxiosOptions`
`callback`	`BodyResponseCallback<T>`

Returns
Type	Description
`void`

Type Parameter
Name	Description
`T`

requestAsync(opts, retry)

protected requestAsync<T>(opts: GaxiosOptions, retry?: boolean): Promise<GaxiosResponse<T>>;

Authenticates the provided HTTP request, processes it and resolves with the returned response.

Parameters
Name	Description
`opts`	`GaxiosOptions` The HTTP request options.
`retry`	`boolean` Whether the current attempt is a retry after a failed attempt. A promise that resolves with the successful response.

Returns
Type	Description
`Promise<GaxiosResponse<T>>`

Type Parameter
Name	Description
`T`

retrieveSubjectToken()

abstract retrieveSubjectToken(): Promise<string>;

Triggered when a external subject token is needed to be exchanged for a GCP access token via GCP STS endpoint. This abstract method needs to be implemented by subclasses depending on the type of external credential used. A promise that resolves with the external subject token.

Returns
Type	Description
`Promise<string>`

setCredentials(credentials)

setCredentials(credentials: Credentials): void;

Provides a mechanism to inject GCP access tokens directly. When the provided credential expires, a new credential, using the external account options, is retrieved.

Parameter
Name	Description
`credentials`	`Credentials` The Credentials object to set on the current client.

Returns
Type	Description
`void`