google-sa-id-token

Fetch ID Token for Service Account when running in GCloud. Lib also caches tokens & auto-refreshes, to improve performance.

By default, tokens will expire 2s earlier that actuall expiry date, to prevent usage of almost expired token. This behaviour can be changed via options.

Installation:

npm i google-sa-id-token

Usage

Get an id Token for default identity (Application Default Credentials)

import { GoogleSaIdToken } from 'google-sa-id-token';

const client = new GoogleSaIdToken();
const token = await client.fetchIdToken(aud);

console.log(token); 
// example output 
// eyJhbGciOiJSUzI1NiIsImtpZCI6IjAxNWFkMDYwZDJiNDQ1MzU5YzliMTA1ZjgwM2RjNzU4YzI5ZjE5ODJkNjFhMWU0ZjFmZGM4ZjBiN2UyNjVjYzQxZTIwMDVlMjM1YzIxMTQ1IiwidHlwIjoiSldUIn0.eyJhdWQiOiJkZWZhdWx0IiwiYXpwIjoiPGV4YW1wbGUtc2VydmljZS1hY2NvdW50LWlkPiIsImVtYWlsIjoiZXhhbXBsZUBwcm9qZWN0LWlkLmlhbS5nc2VydmljZWFjY291bnQuY29tIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsImV4cCI6MTY0MjYzMTI0Mzg2MCwiaWF0IjoxNjQyNjI3NjQzODYwLCJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJzdWIiOiI8ZXhhbXBsZS1zZXJ2aWNlLWFjY291bnQtaWQ-In0.+UpJvARVRn6ESlEr+Gyk4VA+QJV6QzqQP1E7gY2u5D3oKgjBzhlWcxmihDCCO3BFnACes4sMG+VXXqmuQW/pjw==

Get an id Token for default identity (Application Default Credentials) & default aud

import { GoogleSaIdToken } from 'google-sa-id-token';

const client = new GoogleSaIdToken({ defaultAudience: aud });
const token = await client.fetchIdToken();

console.log(token); 
// example output 
// eyJhbGciOiJSUzI1NiIsImtpZCI6IjAxNWFkMDYwZDJiNDQ1MzU5YzliMTA1ZjgwM2RjNzU4YzI5ZjE5ODJkNjFhMWU0ZjFmZGM4ZjBiN2UyNjVjYzQxZTIwMDVlMjM1YzIxMTQ1IiwidHlwIjoiSldUIn0.eyJhdWQiOiJkZWZhdWx0IiwiYXpwIjoiPGV4YW1wbGUtc2VydmljZS1hY2NvdW50LWlkPiIsImVtYWlsIjoiZXhhbXBsZUBwcm9qZWN0LWlkLmlhbS5nc2VydmljZWFjY291bnQuY29tIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsImV4cCI6MTY0MjYzMTI0Mzg2MCwiaWF0IjoxNjQyNjI3NjQzODYwLCJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJzdWIiOiI8ZXhhbXBsZS1zZXJ2aWNlLWFjY291bnQtaWQ-In0.+UpJvARVRn6ESlEr+Gyk4VA+QJV6QzqQP1E7gY2u5D3oKgjBzhlWcxmihDCCO3BFnACes4sMG+VXXqmuQW/pjw==

Add decoded token to response

import { GoogleSaIdToken } from 'google-sa-id-token';

const client = new GoogleSaIdToken();
const token = await client.fetchIdTokenDecoded(aud);

console.log(token); 
// example output
// {
//  raw: "eyJhbGciOiJSUzI1NiIsImtpZCI6IjAxNWFkMDYwZDJiNDQ1MzU5YzliMTA1ZjgwM2RjNzU4YzI5ZjE5ODJkNjFhMWU0ZjFmZGM4ZjBiN2UyNjVjYzQxZTIwMDVlMjM1YzIxMTQ1IiwidHlwIjoiSldUIn0.eyJhdWQiOiJkZWZhdWx0IiwiYXpwIjoiPGV4YW1wbGUtc2VydmljZS1hY2NvdW50LWlkPiIsImVtYWlsIjoiZXhhbXBsZUBwcm9qZWN0LWlkLmlhbS5nc2VydmljZWFjY291bnQuY29tIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsImV4cCI6MTY0MjYzMTI0Mzg2MCwiaWF0IjoxNjQyNjI3NjQzODYwLCJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJzdWIiOiI8ZXhhbXBsZS1zZXJ2aWNlLWFjY291bnQtaWQ-In0.+UpJvARVRn6ESlEr+Gyk4VA+QJV6QzqQP1E7gY2u5D3oKgjBzhlWcxmihDCCO3BFnACes4sMG+VXXqmuQW/pjw==",
//  payload: {
//     aud: 'default',
//     azp: '<example-service-account-id>',
//     email: '[email protected]',
//     email_verified: true,
//     exp: 1642631243860,
//     iat: 1642627643860,
//     iss: 'https://accounts.google.com',
//     sub: '<example-service-account-id>'
//   }
// }

Fetch token, ignoring cache.

import { GoogleSaIdToken } from 'google-sa-id-token';

const client = new GoogleSaIdToken();
const token = await client.fetchIdTokenNoCache(aud);
console.log(token);
// example output
// {
//   raw: ".......", 
//   payload: {
//     ...
//   }
// }

Use different service account

import { GoogleSaIdToken } from 'google-sa-id-token';

const client = new GoogleSaIdToken({ serviceAccountEmail: '[email protected]' });
const token = await client.fetchIdTokenNoCache(aud);

Debug problems

Lib allows you to 'hook in' to different parts of flow, by providing optional logger instance.

import { GoogleSaIdToken } from 'google-sa-id-token';

const logger = {
  info: console.log,
  error: console.error,
}

const client = new GoogleSaIdToken({ logger });
const token = await client.fetchIdToken(aud);

// your console logs will be invoked

Set custom expiry margin for tokens

import { GoogleSaIdToken } from 'google-sa-id-token';

const client = new GoogleSaIdToken({ tokenExpiryMargin: 10000 /* 10 seconds */ });
const token = await client.fetchIdTokenNoCache(aud);

Utils usage, provided by lib

import { GoogleSaIdToken, decodeSaToken } from 'google-sa-id-token';

const client = new GoogleSaIdToken({ tokenExpiryMargin: 10000 /* 10 seconds */ });
const token = await client.fetchIdTokenNoCache(aud);

// utils
const decoded = decodeSaToken(token);
const sampleToken = generateExampleSaToken({ aud: 'override' });

// testing example with jest
jest
  .spyOn(GoogleSaIdToken.prototype, 'fetchIdToken')
  .mockResolvedValue(
    Promise.resolve(generateExampleSaToken({ aud: 'test' }).raw),
  );

Bootstrapped with: create-ts-lib-gh

This project is MIT Licensed.