Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kriasoft/web-auth-library

Authentication library for the browser environment using Web Crypto API
https://github.com/kriasoft/web-auth-library

authentication authorization cloudflare crypto decryption encryption gcp hmac jsonwebtoken jwt oauth oauth2 subtlecrypto token webcrypto webcrypto-api webworkers

Last synced: 1 day ago
JSON representation

Authentication library for the browser environment using Web Crypto API

Host: GitHub
URL: https://github.com/kriasoft/web-auth-library
Owner: kriasoft
License: mit
Created: 2022-05-30T10:57:14.000Z (over 2 years ago)
Default Branch: main
Last Pushed: 2024-08-12T13:03:12.000Z (5 months ago)
Last Synced: 2024-10-30T00:55:27.036Z (3 months ago)
Topics: authentication, authorization, cloudflare, crypto, decryption, encryption, gcp, hmac, jsonwebtoken, jwt, oauth, oauth2, subtlecrypto, token, webcrypto, webcrypto-api, webworkers
Language: TypeScript
Homepage: https://developer.mozilla.org/docs/Web/API/Web_Crypto_API
Size: 2.64 MB
Stars: 100
Watchers: 4
Forks: 9
Open Issues: 16
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

        # Web Auth Library

[![NPM Version](https://img.shields.io/npm/v/web-auth-library?style=flat-square)](https://www.npmjs.com/package/web-auth-library)

[![NPM Downloads](https://img.shields.io/npm/dm/web-auth-library?style=flat-square)](https://www.npmjs.com/package/web-auth-library)

[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg?style=flat-square)](http://www.typescriptlang.org/)

[![Donate](https://img.shields.io/badge/dynamic/json?color=%23ff424d&label=Patreon&style=flat-square&query=data.attributes.patron_count&suffix=%20patrons&url=https%3A%2F%2Fwww.patreon.com%2Fapi%2Fcampaigns%2F233228)](http://patreon.com/koistya)

[![Discord](https://img.shields.io/discord/643523529131950086?label=Chat&style=flat-square)](https://discord.gg/bSsv7XM)

Authentication library for Google Cloud, Firebase, and other cloud providers that uses standard [Web Crypto API](https://developer.mozilla.org/docs/Web/API/Web_Crypto_API) and runs in different environments and runtimes, including but not limited to:

- [Bun](https://bun.sh/)

- [Browsers](https://developer.mozilla.org/docs/Web/API/Web_Crypto_API)

- [Cloudflare Workers](https://workers.cloudflare.com/)

- [Deno](https://deno.land/)

- [Electron](https://www.electronjs.org/)

- [Node.js](https://nodejs.org/)

- [Vercel's Edge Runtime](https://edge-runtime.vercel.app/)

It has minimum dependencies, small bundle size, and optimized for speed and performance.

## Getting Stated

```bash

# Install using NPM

$ npm install web-auth-library --save

# Install using Yarn

$ yarn add web-auth-library

```

## 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](https://cloud.google.com/iam/docs/creating-managing-service-account-keys), `apiKey` is Google Cloud API Key (Firebase API Key), and `projectId` is a Google Cloud project ID.

```ts

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](https://developers.google.com/apis-explorer)

```ts

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

```ts

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:

```ts

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](https://hono.dev/):

```ts

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({ ... });

})

```

## Backers 💰

              

## Related Projects

- [React Starter Kit](https://github.com/kriasoft/react-starter-kit) — front-end template for React and Relay using Jamstack architecture

- [GraphQL API and Relay Starter Kit](https://github.com/kriasoft/graphql-starter) — monorepo template, pre-configured with GraphQL API, React, and Relay

- [Cloudflare Workers Starter Kit](https://github.com/kriasoft/cloudflare-starter-kit) — TypeScript project template for Cloudflare Workers

## How to Contribute

You're very welcome to [create a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)

or send me a message on [Discord](https://discord.gg/bSsv7XM).

In order to unit test this library locally you will need [Node.js](https://nodejs.org/) v18+ with [corepack enabled](https://nodejs.org/api/corepack.html), a Google Cloud [service account key](https://cloud.google.com/iam/docs/keys-create-delete) ([here](https://console.cloud.google.com/iam-admin/serviceaccounts)) and Firebase API Key ([here](https://console.cloud.google.com/apis/credentials)) that you can save into the [`test/test.override.env`](./test/test.env) file, for example:

```

GOOGLE_CLOUD_PROJECT=example

GOOGLE_CLOUD_CREDENTIALS={"type":"service_account","project_id":"example",...}

FIREBASE_API_KEY=AIzaSyAZEmdfRWvEYgZpwm6EBLkYJf6ySIMF3Hy

```

Then run unit tests via `yarn test [--watch]`.

## License

Copyright © 2022-present Kriasoft. This source code is licensed under the MIT license found in the

[LICENSE](https://github.com/kriasoft/web-auth-library/blob/main/LICENSE) file.

---

^{Made with ♥ by Konstantin Tarkus ([@koistya](https://twitter.com/koistya), [blog](https://medium.com/@koistya))

and [contributors](https://github.com/kriasoft/web-auth-library/graphs/contributors).}