W3C Web Authentication API Relying Party for Node.js and Express
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.
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.
$ npm install webauthn
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' })
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:
[store = MemoryAdapter]
- The storage interface for user objects. Defaults
to an object in memory (for testing only).[attestation = 'none']
- the attestation conveyance preference. Setting this to
anything other than 'none'
will require attestation and validate it.[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 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.
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:
credentialEndpoint
.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:
assertionEndpoint
.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
.
Originally adapted from fidoalliance/webauthn-demo.
Run the test suite with npm test
.
MIT © 2019 Stranger Labs, Inc.