Class DownscopedClient (7.13.0)

Defines a set of Google credentials that are downscoped from an existing set of Google OAuth2 credentials. This is useful to restrict the Identity and Access Management (IAM) permissions that a short-lived credential can use. The common pattern of usage is to have a token broker with elevated access generate these downscoped credentials from higher access source credentials and pass the downscoped short-lived access tokens to a token consumer via some secure authenticated channel for limited access to Google Cloud Storage resources.

Inheritance

EventEmitter > AuthClient > DownscopedClient

Package

google-auth-library

Constructors

(constructor)(authClient, credentialAccessBoundary, additionalOptions, quotaProjectId)

constructor(authClient: AuthClient, credentialAccessBoundary: CredentialAccessBoundary, additionalOptions?: RefreshOptions, quotaProjectId?: string);

Instantiates a downscoped client object using the provided source AuthClient and credential access boundary rules. To downscope permissions of a source AuthClient, a Credential Access Boundary that specifies which resources the new credential can access, as well as an upper bound on the permissions that are available on each resource, has to be defined. A downscoped client can then be instantiated using the source AuthClient and the Credential Access Boundary.

Parameters
NameDescription
authClient AuthClient

The source AuthClient to be downscoped based on the provided Credential Access Boundary rules.

credentialAccessBoundary CredentialAccessBoundary

The Credential Access Boundary which contains a list of access boundary rules. Each rule contains information on the resource that the rule applies to, the upper bound of the permissions that are available on that resource and an optional condition to further restrict permissions.

additionalOptions RefreshOptions

Optional additional behavior customization options. These currently customize expiration threshold time and whether to retry on 401/403 API request errors.

quotaProjectId string

Optional quota project id for setting up in the x-goog-user-project header.

Properties

eagerRefreshThresholdMillis

readonly eagerRefreshThresholdMillis: number;

forceRefreshOnFailure

readonly forceRefreshOnFailure: boolean;

Methods

getAccessToken()

getAccessToken(): Promise<DownscopedAccessTokenResponse>;
Returns
TypeDescription
Promise<DownscopedAccessTokenResponse>

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
TypeDescription
Promise<Headers>

refreshAccessTokenAsync()

protected refreshAccessTokenAsync(): Promise<CredentialsWithResponse>;

Forces token refresh, even if unexpired tokens are currently cached. GCP access tokens are retrieved from authclient object/source credential. Then GCP access tokens are exchanged for downscoped access tokens via the token exchange endpoint. A promise that resolves with the fresh downscoped access token.

Returns
TypeDescription
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
NameDescription
opts GaxiosOptions

Request options.

Returns
TypeDescription
GaxiosPromise<T>
Type Parameter
NameDescription
T

request(opts, callback)

request<T>(opts: GaxiosOptions, callback: BodyResponseCallback<T>): void;
Parameters
NameDescription
opts GaxiosOptions
callback BodyResponseCallback<T>
Returns
TypeDescription
void
Type Parameter
NameDescription
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
NameDescription
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
TypeDescription
Promise<GaxiosResponse<T>>
Type Parameter
NameDescription
T

setCredentials(credentials)

setCredentials(credentials: Credentials): void;

Provides a mechanism to inject Downscoped access tokens directly. The expiry_date field is required to facilitate determination of the token expiration which would make it easier for the token consumer to handle.

Parameter
NameDescription
credentials Credentials

The Credentials object to set on the current client.

Returns
TypeDescription
void