W3C Web Authentication API Relying Party for Node.js and Express
npm install webauthn
> W3C Web Authentication API Relying Party for Node.js and Express
WebAuthn is a [W3C standard][w3c] that enables web developers to replace passwords in their applications with [FIDO authentication][fido2]. 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.
[w3c]: https://w3c.github.io/webauthn/
[fido2]: https://fidoalliance.org/fido2/
- 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
This package is not yet ready for use in production software. For more information on security considerations see [W3C Web Authentication][w3c-sec] and [FIDO Security Reference][fido-sec].
[w3c-sec]: https://w3c.github.io/webauthn/#security-considerations
[fido-sec]: https://fidoalliance.org/specs/fido-v2.0-rd-20180702/fido-security-ref-v2.0-rd-20180702.html
``sh`
$ 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.
`javascript
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
// 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
`javascript
import Client from 'webauthn/client'
const client = new Client({ pathPrefix: '/webauthn' })
await client.register({
username: 'AL1C3',
name: 'Alice',
})
// ...
await client.login({ username: 'AL1C3' })
`
[cred-mgmt-api]: https://developer.mozilla.org/en-US/docs/Web/API/Credential_Management_API
[express-js-router]: https://expressjs.com/en/api.html#express.router
[express-js-middleware]: https://expressjs.com/en/guide/using-middleware.html
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[usernameField = 'name']
interface.
- - The name of the field that uniquely identifies a[userFields = ['name', 'displayName'] ]
user.
- - One of:[store = MemoryAdapter]
- 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.
- - The storage interface for user objects. Defaults[credentialEndpoint = '/register']
to an object in memory (for testing only).
- - the path of the credential attestation[assertionEndpoint = '/login']
challenge endpoint.
- - the path of the challenge assertion[challengeEndpoint = '/response']
endpoint.
- - the path of the challenge response[logoutEndpoint = '/logout']
endpoint.
- - the path of the logout endpoint.[enableLogging = true]
- - Enable or disable logging to stdout.
webauthn.initialize()
Returns an [Express Router][express-js-router] with the mounted WebAuthn
endpoints.
webauthn.authenticate([options])
Returns an [Express Middleware][express-js-middleware] that will set req.user
for subsequent middlewares, or produce a 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[credentialEndpoint = '/register']
endpoints.
- - The path of the credential registration[assertionEndpoint = '/login']
endpoint.
- - The path of the challenge assertion[challengeEndpoint = '/response']
endpoint.
- - The path of the challenge response[logoutEndpoint = '/logout']
endpoint.
- - 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.challengeEndpoint
2. Prompt the [Credentials Management API][cred-mgmt-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 .
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.challengeEndpoint
2. Prompt the [Credentials Management API][cred-mgmt-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 .
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`.
* 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
#### 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
* @strangerlabs/webauthn follows the Contributor Covenant Code of Conduct.
MIT © 2019 Stranger Labs, Inc.