File

src/auth/impersonated.ts

Extends

OAuth2Client

Implements

IdTokenProvider

Index

Properties
Methods

Constructor

constructor(options: ImpersonatedOptions)

Impersonated service account credentials.

Create a new access token by impersonating another service account.

Impersonated Credentials allowing credentials issued to a user or service account to impersonate another. The source project using Impersonated Credentials must enable the "IAMCredentials" API. Also, the target service account must grant the orginating principal the "Service Account Token Creator" IAM role.

acquire the impersonated credentials. impersonate. required to grant the final access_token. If set, the sequence of identities must have "Service Account Token Creator" capability granted to the preceding identity. For example, if set to [serviceAccountB, serviceAccountC], the sourceCredential must have the Token Creator role on serviceAccountB. serviceAccountB must have the Token Creator on serviceAccountC. Finally, C must have Token Creator on target_principal. If left unset, sourceCredential must have that role on targetPrincipal. authorization grant. credential should be valid for up to 3600 seconds by default, or 43,200 seconds by extending the token's lifetime, see: https://cloud.google.com/iam/docs/creating-short-lived-service-account-credentials#sa-credentials-oauth

Parameters :
Name Type Optional Description
options ImpersonatedOptions No
  • The configuration object.

Properties

Optional _clientId
Type : string
Inherited from OAuth2Client
Defined in OAuth2Client:426
Optional _clientSecret
Type : string
Inherited from OAuth2Client
Defined in OAuth2Client:429
Optional apiKey
Type : string
Inherited from OAuth2Client
Defined in OAuth2Client:431
eagerRefreshThresholdMillis
Type : number
Inherited from OAuth2Client
Defined in OAuth2Client:435
forceRefreshOnFailure
Type : boolean
Inherited from OAuth2Client
Defined in OAuth2Client:437
Optional projectId
Type : string
Inherited from OAuth2Client
Defined in OAuth2Client:433
Optional refreshHandler
Type : GetRefreshHandlerCallback
Inherited from OAuth2Client
Defined in OAuth2Client:439

Methods

Async fetchIdToken
fetchIdToken(targetAudience: string, options?: FetchIdTokenOptions)

Generates an OpenID Connect ID token for a service account.

Reference Documentation

Parameters :
Name Type Optional Description
targetAudience string No

the audience for the fetched ID token.

options FetchIdTokenOptions Yes

the for the request

Returns : Promise<string>

an OpenID Connect ID token

generateAuthUrl
generateAuthUrl(opts: GenerateAuthUrlOpts)
Inherited from OAuth2Client
Defined in OAuth2Client:533

Generates URL for consent page landing.

Parameters :
Name Type Optional Default value Description
opts GenerateAuthUrlOpts No {}

Options.

Returns : string

URL to consent page.

generateCodeVerifier
generateCodeVerifier()
Inherited from OAuth2Client
Defined in OAuth2Client:554
Returns : void
Async generateCodeVerifierAsync
generateCodeVerifierAsync()
Inherited from OAuth2Client
Defined in OAuth2Client:570

Convenience method to automatically generate a code_verifier, and its resulting SHA256. If used, this must be paired with a S256 code_challenge_method.

For a full example see: https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/oauth2-codeVerifier.js

getAccessToken
getAccessToken()
Inherited from OAuth2Client
Defined in OAuth2Client:757

Get a non-expired access token, after refreshing if necessary

Returns : Promise<GetAccessTokenResponse>
getFederatedSignonCerts
getFederatedSignonCerts()
Inherited from OAuth2Client
Defined in OAuth2Client:1131

Gets federated sign-on certificates to use for verifying identity tokens. Returns certs as array structure, where keys are key ids, and values are certificates in either PEM or JWK format.

Async getFederatedSignonCertsAsync
getFederatedSignonCertsAsync()
Inherited from OAuth2Client
Defined in OAuth2Client:1146
getIapPublicKeys
getIapPublicKeys()
Inherited from OAuth2Client
Defined in OAuth2Client:1219

Gets federated sign-on certificates to use for verifying identity tokens. Returns certs as array structure, where keys are key ids, and values are certificates in either PEM or JWK format.

Returns : Promise<IapPublicKeysResponse>
Async getIapPublicKeysAsync
getIapPublicKeysAsync()
Inherited from OAuth2Client
Defined in OAuth2Client:1234
Returns : Promise<IapPublicKeysResponse>
Async getRequestHeaders
getRequestHeaders(url?: string)
Inherited from OAuth2Client
Defined in OAuth2Client:810

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.

In OAuth2Client, the result has the form: { Authorization: 'Bearer ' }

Parameters :
Name Type Optional Description
url string Yes

The optional url being authorized

Returns : Promise<Headers>
Static getRevokeTokenUrl
getRevokeTokenUrl(token: string)
Inherited from OAuth2Client
Defined in OAuth2Client:885

Generates an URL to revoke the given token.

Parameters :
Name Type Optional Description
token string No

The existing token to be revoked.

Returns : string
getToken
getToken(code: string)
Inherited from OAuth2Client
Defined in OAuth2Client:599

Gets the access token for the given code.

Parameters :
Name Type Optional Description
code string No

The authorization code.

Returns : Promise<GetTokenResponse>
Async getTokenInfo
getTokenInfo(accessToken: string)
Inherited from OAuth2Client
Defined in OAuth2Client:1104

Obtains information about the provisioned access token. Especially useful if you want to check the scopes that were provisioned to a given token.

user info.

Parameters :
Name Type Optional Description
accessToken string No

Required. The Access Token for which you want to get user info.

Returns : Promise<TokenInfo>
refreshAccessToken
refreshAccessToken()
Inherited from OAuth2Client
Defined in OAuth2Client:729

Retrieves the access token using refresh token

Returns : Promise<RefreshAccessTokenResponse>
request
request(opts: GaxiosOptions)
Inherited from OAuth2Client
Defined in OAuth2Client:953
Type parameters :
  • T

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

Parameters :
Name Type Optional Description
opts GaxiosOptions No

Request options.

Returns : GaxiosPromise<T>

Request object

revokeCredentials
revokeCredentials()
Inherited from OAuth2Client
Defined in OAuth2Client:921

Revokes access token and clears the credentials object

Returns : GaxiosPromise<RevokeCredentialsResult>
revokeToken
revokeToken(token: string)
Inherited from OAuth2Client
Defined in OAuth2Client:895

Revokes the access given to token.

Parameters :
Name Type Optional Description
token string No

The existing token to be revoked.

Returns : GaxiosPromise<RevokeCredentialsResult>
verifyIdToken
verifyIdToken(options: VerifyIdTokenOptions)
Inherited from OAuth2Client
Defined in OAuth2Client:1054

Verify id token is token by checking the certs and audience

Parameters :
Name Type Optional Description
options VerifyIdTokenOptions No

that contains all options.

verifySignedJwtWithCerts
verifySignedJwtWithCerts()
Inherited from OAuth2Client
Defined in OAuth2Client:1251
Returns : void
Async verifySignedJwtWithCertsAsync
verifySignedJwtWithCertsAsync(jwt: string, certs: Certificates | PublicKeys, requiredAudience?: string | string[], issuers?: string[], maxExpiry?: number)
Inherited from OAuth2Client
Defined in OAuth2Client:1269

Verify the id token is signed with the correct certificate and is from the correct audience.

Parameters :
Name Type Optional Description
jwt string No

The jwt to verify (The ID Token in this case).

certs Certificates | PublicKeys No

The array of certs to test the jwt against.

requiredAudience string | string[] Yes

The audience to test the jwt against.

issuers string[] Yes

The allowed issuers of the jwt (Optional).

maxExpiry number Yes

The max expiry the certificate can be (Optional).

Returns : unknown

Returns a promise resolving to LoginTicket on verification.

import {GetTokenResponse, OAuth2Client, RefreshOptions} from './oauth2client';
import {AuthClient} from './authclient';
import {IdTokenProvider} from './idtokenclient';
import {GaxiosError} from 'gaxios';

export interface ImpersonatedOptions extends RefreshOptions {
  /**
   * Client used to perform exchange for impersonated client.
   */
  sourceClient?: AuthClient;
  /**
   * The service account to impersonate.
   */
  targetPrincipal?: string;
  /**
   * Scopes to request during the authorization grant.
   */
  targetScopes?: string[];
  /**
   * The chained list of delegates required to grant the final access_token.
   */
  delegates?: string[];
  /**
   * Number of seconds the delegated credential should be valid.
   */
  lifetime?: number | 3600;
  /**
   * API endpoint to fetch token from.
   */
  endpoint?: string;
}

export const IMPERSONATED_ACCOUNT_TYPE = 'impersonated_service_account';

export interface TokenResponse {
  accessToken: string;
  expireTime: string;
}

export interface FetchIdTokenOptions {
  /**
   * Include the service account email in the token.
   * If set to `true`, the token will contain `email` and `email_verified` claims.
   */
  includeEmail: boolean;
}

export interface FetchIdTokenResponse {
  /** The OpenId Connect ID token. */
  token: string;
}

export class Impersonated extends OAuth2Client implements IdTokenProvider {
  private sourceClient: AuthClient;
  private targetPrincipal: string;
  private targetScopes: string[];
  private delegates: string[];
  private lifetime: number;
  private endpoint: string;

  /**
   * Impersonated service account credentials.
   *
   * Create a new access token by impersonating another service account.
   *
   * Impersonated Credentials allowing credentials issued to a user or
   * service account to impersonate another. The source project using
   * Impersonated Credentials must enable the "IAMCredentials" API.
   * Also, the target service account must grant the orginating principal
   * the "Service Account Token Creator" IAM role.
   *
   * @param {object} options - The configuration object.
   * @param {object} [options.sourceClient] the source credential used as to
   * acquire the impersonated credentials.
   * @param {string} [options.targetPrincipal] the service account to
   * impersonate.
   * @param {string[]} [options.delegates] the chained list of delegates
   * required to grant the final access_token. If set, the sequence of
   * identities must have "Service Account Token Creator" capability granted to
   * the preceding identity. For example, if set to [serviceAccountB,
   * serviceAccountC], the sourceCredential must have the Token Creator role on
   * serviceAccountB. serviceAccountB must have the Token Creator on
   * serviceAccountC. Finally, C must have Token Creator on target_principal.
   * If left unset, sourceCredential must have that role on targetPrincipal.
   * @param {string[]} [options.targetScopes] scopes to request during the
   * authorization grant.
   * @param {number} [options.lifetime] number of seconds the delegated
   * credential should be valid for up to 3600 seconds by default, or 43,200
   * seconds by extending the token's lifetime, see:
   * https://cloud.google.com/iam/docs/creating-short-lived-service-account-credentials#sa-credentials-oauth
   * @param {string} [options.endpoint] api endpoint override.
   */
  constructor(options: ImpersonatedOptions = {}) {
    super(options);
    this.credentials = {
      expiry_date: 1,
      refresh_token: 'impersonated-placeholder',
    };
    this.sourceClient = options.sourceClient ?? new OAuth2Client();
    this.targetPrincipal = options.targetPrincipal ?? '';
    this.delegates = options.delegates ?? [];
    this.targetScopes = options.targetScopes ?? [];
    this.lifetime = options.lifetime ?? 3600;
    this.endpoint = options.endpoint ?? 'https://iamcredentials.googleapis.com';
  }

  /**
   * Refreshes the access token.
   * @param refreshToken Unused parameter
   */
  protected async refreshToken(
    refreshToken?: string | null
  ): Promise<GetTokenResponse> {
    try {
      await this.sourceClient.getAccessToken();
      const name = 'projects/-/serviceAccounts/' + this.targetPrincipal;
      const u = `${this.endpoint}/v1/${name}:generateAccessToken`;
      const body = {
        delegates: this.delegates,
        scope: this.targetScopes,
        lifetime: this.lifetime + 's',
      };
      const res = await this.sourceClient.request<TokenResponse>({
        url: u,
        data: body,
        method: 'POST',
      });
      const tokenResponse = res.data;
      this.credentials.access_token = tokenResponse.accessToken;
      this.credentials.expiry_date = Date.parse(tokenResponse.expireTime);
      return {
        tokens: this.credentials,
        res,
      };
    } catch (error) {
      if (!(error instanceof Error)) throw error;

      let status = 0;
      let message = '';

      if (error instanceof GaxiosError) {
        status = error?.response?.data?.error?.status;
        message = error?.response?.data?.error?.message;
      }

      if (status && message) {
        error.message = `${status}: unable to impersonate: ${message}`;
        throw error;
      } else {
        error.message = `unable to impersonate: ${error}`;
        throw error;
      }
    }
  }

  /**
   * Generates an OpenID Connect ID token for a service account.
   *
   * {@link https://cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/generateIdToken Reference Documentation}
   *
   * @param targetAudience the audience for the fetched ID token.
   * @param options the for the request
   * @return an OpenID Connect ID token
   */
  async fetchIdToken(
    targetAudience: string,
    options?: FetchIdTokenOptions
  ): Promise<string> {
    await this.sourceClient.getAccessToken();

    const name = `projects/-/serviceAccounts/${this.targetPrincipal}`;
    const u = `${this.endpoint}/v1/${name}:generateIdToken`;
    const body = {
      delegates: this.delegates,
      audience: targetAudience,
      includeEmail: options?.includeEmail ?? true,
    };
    const res = await this.sourceClient.request<FetchIdTokenResponse>({
      url: u,
      data: body,
      method: 'POST',
    });

    return res.data.token;
  }
}

results matching ""

    No results matching ""