WebAuthn

W3C Web Authentication API Relying Party for Node.js and Express

WebAuthn is a W3C standard that enables web developers to replace passwords in their applications with FIDO authentication. This repository implements a NPM package for use in Node.js services. This package is in active development and not yet ready for production use. You can use it to kick the tires on WebAuthn. Please file issues to ask questions or provide feedback.

Table of Contents

• WebAuthn
  • Table of Contents
  • Security
  • Install
  • Usage
  • API
    • Relying Party
    • Storage Adapater
    • Browser Client
  • Maintainers
  • Contributing
    • Issues
    • Pull requests
      • Policy
      • Style guide
      • Code reviews
    • Code of conduct
  • License

Security

This package is not yet ready for use in production software. For more information on security considerations see W3C Web Authentication and FIDO Security Reference.

Install

$ npm install webauthn

Usage

See examples for a complete example. The package currently works on its own and we plan to support Passport.js integration in future releases.

const WebAuthn = require('webauthn')

// configure express and session middleware; see "examples" in this repository
// ...

// Create webauthn
const webauthn = new WebAuthn({
  origin: 'http://localhost:3000',
  usernameField: 'username',
  userFields: {
    username: 'username',
    name: 'displayName',
  },
  store: new LevelAdapter(),
  // OR
  // store: {
  //   put: async (id, value) => {/* return <void> */},
  //   get: async (id) => {/* return User */},
  //   search: async (search) => {/* return { [username]: User } */},
  //   delete: async (id) => {/* return boolean */},
  // },
  rpName: 'Stranger Labs, Inc.',
  enableLogging: false,
})

// Mount webauthn endpoints
app.use('/webauthn', webauthn.initialize())

// Endpoint without passport
app.get('/secret', webauthn.authenticate(), (req, res) => {
  res.status(200).json({ status: 'ok', message: 'Super Secret!' })
})

Client

import Client from 'webauthn/client'

const client = new Client({ pathPrefix: '/webauthn' })

await client.register({
  username: 'AL1C3',
  name: 'Alice',
})

// ...

await client.login({ username: 'AL1C3' })

API

Relying Party

new WebAuthn(options)

The main entrypoint for creating a new WebAuthn RP instance. options is used to configure the behaviour of the RP. Available options include:

• origin - The origin of the deployed application.
• rpName - The display name of RP. This will be shown in the WebAuthn consent interface.
• [usernameField = 'name'] - The name of the field that uniquely identifies a user.
• [userFields = ['name', 'displayName'] ] - One of:
  • An array of properties from registration request to be included in the saved user object
  • An object mapping, where the key is the name of a property from the registration request to be included in the user object and the value is the name of that property on the user object.
• [store = MemoryAdapter] - The storage interface for user objects. Defaults to an object in memory (for testing only).
• [credentialEndpoint = '/register'] - the path of the credential attestation challenge endpoint.
• [assertionEndpoint = '/login'] - the path of the challenge assertion endpoint.
• [challengeEndpoint = '/response'] - the path of the challenge response endpoint.
• [logoutEndpoint = '/logout'] - the path of the logout endpoint.
• [enableLogging = true] - Enable or disable logging to stdout.

webauthn.initialize()

Returns an Express Router with the mounted WebAuthn endpoints.

webauthn.authenticate([options])

Returns an Express Middleware that will set req.user for subsequent middlewares, or produce a 401 Unauthorized error if the user is not authenticated. Available options include:

• [failureRedirect] - If the user fails to authenticate then they will be redirected to the supplied URL.

Storage Adapater

Storage adapters provide an interface to the WebAuthn RP to store and retrieve data necessary for authentication, such as authenticator public keys. Storage adapters must implement the following interface:

async get (id)

Retrieves and returns the previously stored object with the provided id.

async put (id, value)

Stores an object so that it may be retrieved with the provided id. Returns nothing.

async search (startsWith, [options])

Returns a mapping of objects where the id of the objects return starts with the provided query value. Available options include:

• limit: Return the first N results.
• reverse: Return results in reverse lexicographical order. If used in conjunction with limit then the last N results are returned.

async delete (id)

Delete a previously stored object. Returns a boolean indicating success.

Browser Client

new Client([options])

Constructs a new client for handling interaction with the Web Authentication API and the server authentication endpoints. Available options include:

• [pathPrefix = '/webauthn'] - A mounting prefix to all authorization endpoints.
• [credentialEndpoint = '/register'] - The path of the credential registration endpoint.
• [assertionEndpoint = '/login'] - The path of the challenge assertion endpoint.
• [challengeEndpoint = '/response'] - The path of the challenge response endpoint.
• [logoutEndpoint = '/logout'] - The path of the logout endpoint.

Returns a new client instance.

async client.register(data)

Completes a start-to-finish registration of a new authenticator at the remote service with the following steps:

1. Fetch a register credential challenge from the remote server's credentialEndpoint.
2. Prompt the Credentials Management API to generate a new local credential.
   • The Credentials Management API prompts the user for consent.
   • The challenge is signed using the user-selected method and returned.
3. The signed challenge is returned to the remote server's challengeEndpoint.

Returns the response of the request to the challengeEndpoint.

async client.login(data)

Completes a start-to-finish assertion challenge on a previously registered remote service with the following steps:

1. Fetch an assertion challenge from the remote server's assertionEndpoint.
2. Prompt the Credentials Management API to get an existing local credential and sign the response.
   • The Credentials Management API prompts the user for consent.
   • The challenge is signed and returned.
3. The signed challenge is returned to the remote server's challengeEndpoint.

Returns the response of the request to the challengeEndpoint.

async client.logout()

Destroys the current session on the remote server. Returns the result of the request to the logoutEndpoint.

Maintainers

@Terrahop

@EternalDeiwos

@christiansmith

Contributing

Issues

• Please file issues :)
• When writing a bug report, include relevant details such as platform, version, relevant data, and stack traces
• Ensure to check for existing issues before opening new ones
• Read the documentation before asking questions
• It is strongly recommended to open an issue before hacking and submitting a PR

Pull requests

Policy

• We're not presently accepting unsolicited pull requests
• Create an issue to discuss proposed features before submitting a pull request
• Create an issue to propose changes of code style or introduce new tooling
• Ensure your work is harmonious with the overall direction of the project
• Ensure your work does not duplicate existing effort
• Keep the scope compact; avoid PRs with more than one feature or fix
• Code review with maintainers is required before any merging of pull requests
• New code must respect the style guide and overall architecture of the project
• Be prepared to defend your work

Style guide

• Conventional Changelog
• ECMAScript
• Standard JavaScript
• Standard README
• jsdoc

Code reviews

• required before merging PRs
• reviewers MUST run and test the code under review

Code of conduct

• @strangerlabs/webauthn follows the Contributor Covenant Code of Conduct.

License

MIT © 2019 Stranger Labs, Inc.