Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/passwordless-id/webauthn
Webauthn / passkeys helper library to make your life easier. Client side, server side and demo included.
https://github.com/passwordless-id/webauthn
authentication passkeys passwordless webauthn
Last synced: 2 months ago
JSON representation
Webauthn / passkeys helper library to make your life easier. Client side, server side and demo included.
- Host: GitHub
- URL: https://github.com/passwordless-id/webauthn
- Owner: passwordless-id
- License: mit
- Created: 2022-08-11T07:41:33.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-14T06:45:11.000Z (3 months ago)
- Last Synced: 2024-10-29T22:53:56.725Z (3 months ago)
- Topics: authentication, passkeys, passwordless, webauthn
- Language: TypeScript
- Homepage: https://webauthn.passwordless.id
- Size: 2.03 MB
- Stars: 451
- Watchers: 8
- Forks: 53
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-webauthn - Passwordless.ID: WebAuthn lib - A simple, minimal, opinionated typescript wrapper around WebAuthn. Features both client side to invoke WebAuthn and server side to verify credentials. (Server Libraries)
README
@passwordless-id/webauthn
=========================
[](https://www.npmjs.com/package/@passwordless-id/webauthn)
[](https://bundlephobia.com/package/@passwordless-id/webauthn)
[](https://www.npmjs.com/package/@passwordless-id/webauthn)
[](https://github.com/passwordless-id/webauthn)
[](https://github.com/sponsors/passwordless-id)
> This library greatly simplifies the usage of **passkeys** by invoking the [WebAuthn protocol](https://w3c.github.io/webauthn/) more conveniently. It is [open source](https://github.com/passwordless-id/webauthn), opinionated, dependency-free and minimalistic.
>
> This library is provided by [Passwordless.ID](https://passwordless.id), a free public identity provider.
👀 Demos
---------
- [Basic Demo](https://webauthn.passwordless.id/demos/basic.html)
- [Passkeys autocomplete](https://webauthn.passwordless.id/demos/conditional-ui.html)
- [Testing Playground](https://webauthn.passwordless.id/demos/playground.html)
- [Authenticators list](https://webauthn.passwordless.id/demos/authenticators.html)
- [Docs](https://webauthn.passwordless.id)
These demos are plain HTML/JS, not minimized. Just open the sources in your browser if you are curious.
📦 Installation
----------------
### Modules (recommended)
```bash
npm install @passwordless-id/webauthn
```
The base package contains both client and server side modules. You can import the `client` submodule or the `server` depending on your needs.
```js
import {client} from '@passwordless-id/webauthn'
import {server} from '@passwordless-id/webauthn'
```
*Note: the brackets in the import are important!*
### Alternatives
For **browsers**, it can be imported using a CDN link in the page, or even inside the script itself.
```html
import {client} from src="https://cdn.jsdelivr.net/npm/@passwordless-id/[email protected]/dist/webauthn.min.js"
```
Lastly, a **CommonJS** variant is also available for old Node stacks, to be imported using `require('@passwordless-id/webauthn')`. It's usage is discouraged though, in favor of the default ES modules.
Note that at least NodeJS **19+** is necessary. (The reason is that previous Node versions had no `WebCrypto` being globally available, making it impossible to have a "universal build")
🚀 Getting started
-------------------
There are multiple ways to use and invoke the WebAuthn protocol.
What follows is just an example of the most straightforward use case.
### Registration
```
import {client} from '@passwordless-id/webauthn'
await client.register({
challenge: 'a random base64url encoded buffer from the server',
user: 'John Doe'
})
```
By default, this registers a passkey on any authenticator (local or roaming) with `preferred` user verification. For further options, see [→ Registration docs](https://webauthn.passwordless.id/registration/)
### Authentication
```
import {client} from '@passwordless-id/webauthn'
await client.authenticate({
challenge: 'a random base64url encoded buffer from the server'
})
```
By default, this triggers the native passkey selection dialog, for any authenticator (local or roaming) and with `preferred` user verification. For further options, see [→ Authentication docs](https://webauthn.passwordless.id/authentication/)
### Verification
```
import {server} from '@passwordless-id/webauthn'
await server.verifyRegistration(registration, expected)
await server.verifyAuthentication(authentication, expected)
```
[→ Verification docs](https://webauthn.passwordless.id/verification/)
📃 Changelog
-------------
The version 2 introduced breaking changes, different default behavior and different intermediate format. Basically, it's a complete overhaul and to understand "why" this version 2 was made, I recommend reading this [blog post](https://blog.passwordless.id/passkeys-webauthn-library-v20-is-there#heading-why-a-version-2). In a very summarized way, it is to enhance support for security keys by default, reflect latest changes in the underlying specs and improve cross-compatibility with other server side libraries.
Some core changes are:
- Use platform authenticator by default => authenticator selection pops up by default
- `authenticatorType` was removed => use `hints` instead
- User verification default: `required` => `preferred`
- Timeout: 1 minute => no timeout
- Response format changed
- Transports as part of `allowCredentials`
The docs for the legacy version 1.x are found [here](https://webauthn.passwordless.id/version-1)