Web Auth Library Versions Save

• Send Content-Type header when fetching an access token from Google (#12) — @unkhz
• Fix checking for the availability of caches.default throwing an error in Bun runtime (#13) — @unkhz
• Relax option.waitUntil signature to use (promise: Promise<any) => void (#14) — @koistya

• Add UserToken type definition; verifyIdToken(..) returns Promise<UserToken> (#10)
• Print a warning when the options.waitUntil argument is omitted in Cloudflare Workers environment (#10)

Usage Examples

Verify the user ID Token issued by Google or Firebase

NOTE: The credentials argument in the examples below is expected to be a serialized JSON string of a Google Cloud service account key, apiKey is Google Cloud API Key (Firebase API Key), and projectId is a Google Cloud project ID.

import { verifyIdToken } from "web-auth-library/google";

const token = await verifyIdToken({
  idToken,
  credentials: env.GOOGLE_CLOUD_CREDENTIALS,
});

// => {
//   iss: 'https://securetoken.google.com/example',
//   aud: 'example',
//   auth_time: 1677525930,
//   user_id: 'temp',
//   sub: 'temp',
//   iat: 1677525930,
//   exp: 1677529530,
//   firebase: {}
// }

Create an access token for accessing Google Cloud APIs

import { getAccessToken } from "web-auth-library/google";

// Generate a short lived access token from the service account key credentials
const accessToken = await getAccessToken({
  credentials: env.GOOGLE_CLOUD_CREDENTIALS,
  scope: "https://www.googleapis.com/auth/cloud-platform",
});

// Make a request to one of the Google's APIs using that token
const res = await fetch(
  "https://cloudresourcemanager.googleapis.com/v1/projects",
  {
    headers: { Authorization: `Bearer ${accessToken}` },
  }
);

Create a custom ID token using Service Account credentials

import { getIdToken } from "web-auth-library/google";

const idToken = await getIdToken({
  credentials: env.GOOGLE_CLOUD_CREDENTIALS,
  audience: "https://example.com",
});

An alternative way passing credentials

Instead of passing credentials via options.credentials argument, you can also let the library pick up credentials from the list of environment variables using standard names such as GOOGLE_CLOUD_CREDENTIALS, GOOGLE_CLOUD_PROJECT, FIREBASE_API_KEY, for example:

import { verifyIdToken } from "web-auth-library/google";

const env = { GOOGLE_CLOUD_CREDENTIALS: "..." };
const token = await verifyIdToken({ idToken, env });

Optimize cache renewal background tasks

Pass the optional waitUntil(promise) function provided by the target runtime to optimize the way authentication tokens are being renewed in background. For example, using Cloudflare Workers and Hono.js:

import { Hono } from "hono";
import { verifyIdToken } from "web-auth-library/google";

const app = new Hono();

app.get("/", ({ env, executionCtx, json }) => {
  const idToken = await verifyIdToken({
    idToken: "...",
    waitUntil: executionCtx.waitUntil,
    env,
  });

  return json({ ... });
})

Retrieving an ID token for the target audience

import { getAuthToken } from "web-auth-library/google";

const token = await getAuthToken({
  credentials: env.GOOGLE_CLOUD_CREDENTIALS,
  audience: "https://example.com",
});
// => {
//   idToken: "eyJhbGciOiJSUzI1NiIsImtpZ...",
//   audience: "https://example.com",
//   expires: 1654199401,
// }

Decoding an ID token

import { jwt } from "web-auth-library/google";

jwt.decode(idToken);
// {
//   header: {
//     alg: 'RS256',
//     kid: '38f3883468fc659abb4475f36313d22585c2d7ca',
//     typ: 'JWT'
//   },
//   payload: {
//     iss: 'https://accounts.google.com',
//     sub: '118363561738753879481'
//     aud: 'https://example.com',
//     azp: '[email protected]',
//     email: '[email protected]',
//     email_verified: true,
//     exp: 1654199401,
//     iat: 1654195801,
//   },
//   data: 'eyJhbGciOiJ...',
//   signature: 'MDzBStL...'
// }

Verifying an ID token

import { verifyIdToken } from "web-auth-library/google";

const token = await verifyIdToken(idToken, { audience: "https://example.com" });
// => {
//   iss: 'https://accounts.google.com',
//   sub: '118363561738753879481'
//   aud: 'https://example.com',
//   azp: '[email protected]',
//   email: '[email protected]',
//   email_verified: true,
//   exp: 1654199401,
//   iat: 1654195801,
// }

• refactor: Move Google Cloud specific code into its own namespace [#2]

Retrieving an access token for GCP

import { getAuthToken } from "web-auth-library/gcp";

// Get an access token for interacting with Google Cloud Platform APIs.
const token = await getAuthToken({
  credentials: env.GOOGLE_CLOUD_CREDENTIALS,
  scope: "https://www.googleapis.com/auth/cloud-platform",
});
// => {
//   accessToken: "ya29.c.b0AXv0zTOQVv0...",
//   type: "Bearer",
//   expires: 1653855236,
// }

Retrieving an ID token for the arbitrary resource

import { getAuthToken } from "web-auth-library/gcp";

// Get an ID token for the target resource (audience)
const token = await getAuthToken({
  credentials: env.GOOGLE_CLOUD_CREDENTIALS,
  audience: "https://example.com",
});
// => {
//   idToken: "eyJhbGciOiJSUzI1NiIsImtpZ...",
//   audience: "https://example.com",
//   expires: 1653855236,
// }

Generating a digital signature

import { importKey, sign, getCredentials } from "web-auth-library/gcp";

// Convert GCP service account key into `CryptoKey` object
const credentials = getCredentials(env.GOOGLE_CLOUD_CREDENTIALS);
const signingKey = await importKey(credentials.private_key, ["sign"]);

// Generate a digital signature
const signature = await sign(signingKey, "xxx");

A collection of utility functions for working with Web Crypto API.

How to Install

# Install using NPM
$ npm install web-auth-library --save-dev

# Install using Yarn
$ yarn add web-auth-library

Usage Example

Retrieving an access token from the Google's OAuth 2.0 authorization server using a service account key (JSON), in Cloudflare Workers environment:

import { getAuthToken } from "web-auth-library";

export default {
  async fetch(req, env) {
    // Get an access token for interacting with Google Cloud Platform APIs.
    const token = await getAuthToken({
      credentials: env.GOOGLE_CLOUD_CREDENTIALS,
      scope: "https://www.googleapis.com/auth/cloud-platform",
    });
    // => {
    //   accessToken: "ya29.c.b0AXv0zTOQVv0...",
    //   type: "Bearer",
    //   expires: 1653855236,
    // }
    return fetch("https://cloudresourcemanager.googleapis.com/v1/projects", {
      headers: {
        authorization: `Bearer ${token.accessToken}`,
      },
    });
  },
} as ExportedHandler;

Where env.GOOGLE_CLOUD_CREDENTIALS is an environment variable / secret containing a base64-encoded service account key obtained from the Google Cloud Platform.

How to Contribute

You're very welcome to create a PR or send me a message on Discord.