new Passwordless()
Passwordless is a node.js module for express that allows authentication and
authorization without passwords but simply by sending tokens via email or
other means. It utilizes a very similar mechanism as many sites use for
resetting passwords. The module was inspired by Justin Balthrop's article
"Passwords are Obsolete"
- Source:
Methods
(private) _generateNumberToken(max) → {Number}
Generates a strong random number between 0 and a maximum value. The
maximum value cannot exceed 2^32
Parameters:
| Name | Type | Description |
|---|---|---|
max |
Number | Maximum number to be generated |
- Source:
Throws:
-
Will throw an error if there is no sufficient entropy accumulated
- Type
- Error
Returns:
Random number between 0 and max
- Type
- Number
(private) _generateToken(randomBytes) → {function}
Generates a random token using Node's crypto rng
Parameters:
| Name | Type | Description |
|---|---|---|
randomBytes |
Number | Random bytes to be generated |
- Source:
Throws:
-
Will throw an error if there is no sufficient entropy accumulated
- Type
- Error
Returns:
token-generator function
- Type
- function
(private) _redirectWithSessionSave(req, res, next, target)
Avoids a bug in express that might lead to a redirect
before the session is actually saved
Parameters:
| Name | Type | Description |
|---|---|---|
req |
Object | Node's http req object |
res |
Object | Node's http res object |
next |
function | Middleware callback |
target |
String | URL to redirect to |
- Source:
(private) _send401(res)
Sends a 401 error message back to the user
Parameters:
| Name | Type | Description |
|---|---|---|
res |
Object | Node's http res object |
- Source:
acceptToken(optionsopt) → {ExpressMiddleware}
Returns express middleware which will look for token / UID query parameters and
authenticate the user if they are provided and valid. A typical URL that is
accepted by acceptToken() does look like this:
http://www.example.com?token=TOKEN&uid=UID
Simply calls the next middleware in case no token / uid has been submitted or if
the supplied token / uid are not valid
Parameters:
| Name | Type | Attributes | Description | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
<optional> |
Properties
|
- Source:
Throws:
-
Will throw an error if there is no valid TokenStore, if failureFlash or successFlash is used without flash middleware or allowPost is used without body parser middleware
- Type
- Error
Returns:
Express middleware
- Type
- ExpressMiddleware
Example
app.use(passwordless.sessionSupport());
// Look for tokens in any URL requested from the server
app.use(passwordless.acceptToken());
addDelivery(nameopt, sendToken, optionsopt)
Adds a new delivery method to Passwordless used to transmit tokens to the user. This could,
for example, be an email client or a sms client. If only one method is used, no name has to
provided as it will be the default delivery method. If several methods are used and added,
they will have to be named.
Parameters:
| Name | Type | Attributes | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name |
String |
<optional> |
Name of the strategy. Not needed if only one method is added | ||||||||||||||||
sendToken |
sendToken | Method that will be called as function(tokenToSend, uidToSend, recipient, callback, req) to transmit the token to the user. tokenToSend contains the token, uidToSend the UID that has to be part of the token URL, recipient contains the target such as an email address or a phone number depending on the user input, and callback has to be called either with no parameters or with callback({String}) in case of any issues during delivery | |||||||||||||||||
options |
Object |
<optional> |
Properties
|
- Source:
Example
passwordless.init(new MongoStore(pathToMongoDb));
passwordless.addDelivery(
function(tokenToSend, uidToSend, recipient, callback, req) {
// Send out token
smtpServer.send({
text: 'Hello!\nYou can now access your account here: '
+ host + '?token=' + tokenToSend + '&uid=' + encodeURIComponent(uidToSend),
from: yourEmail,
to: recipient,
subject: 'Token for ' + host
}, function(err, message) {
if(err) {
console.log(err);
}
callback(err);
});
});
init(tokenStore, optionsopt)
Initializes Passwordless and has to be called before any methods are called
Parameters:
| Name | Type | Attributes | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
tokenStore |
TokenStore | An instance of a TokenStore used to store and authenticate the generated tokens | |||||||||||||||||
options |
Object |
<optional> |
Properties
|
- Source:
Throws:
-
Will throw an error if called without an instantiated TokenStore
- Type
- Error
logout(optionsopt) → {ExpressMiddleware}
Logs out the current user and invalidates any tokens that are still valid for the user
Parameters:
| Name | Type | Attributes | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
<optional> |
Properties
|
- Source:
Throws:
-
Will throw an error if successFlash is used without flash middleware
- Type
- Error
Returns:
Express middleware
- Type
- ExpressMiddleware
Example
router.get('/logout', passwordless.logout( {options.successFlash: 'All done!'} ),
function(req, res) {
res.redirect('/');
});
requestToken(getUserID, optionsopt) → {ExpressMiddleware}
Requests a token from Passwordless for a specific user and calls the delivery strategy
to send the token to the user. Sends back a 401 error message if the user is not valid
or a 400 error message if no user information has been transmitted at all. By default,
POST params will be expected
Parameters:
| Name | Type | Attributes | Description | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
getUserID |
getUserID | The function called to resolve the supplied user contact information (e.g. email) into a proper user ID: function(user, delivery, callback, req) where user contains the contact details provided, delivery the method used, callback expects a call in the format callback(error, user), where error is either null or an error message and user is either null if not user has been found or the user ID. req contains the Express request object | |||||||||||||||||||||||||||||||||
options |
Object |
<optional> |
Properties
|
- Source:
Throws:
-
Will throw an error if failureFlash is used without flash middleware, failureFlash is used without failureRedirect, successFlash is used without flash middleware, no body parser is used and POST parameters are expected, or if no delivery method has been added
- Type
- Error
Returns:
Express middleware
- Type
- ExpressMiddleware
Example
router.post('/sendtoken',
passwordless.requestToken(
function(user, delivery, callback, req) {
// usually you would want something like:
User.find({email: user}, callback(ret) {
if(ret)
callback(null, ret.id)
else
callback(null, null)
})
}),
function(req, res) {
res.render('sent');
});restricted(optionsopt) → {ExpressMiddleware}
Returns express middleware that ensures that only successfully authenticated users
have access to any middleware or responses that follows this middleware. Can either
be used for individual URLs or a certain path and any sub-elements. By default, a
401 error message is returned if the user has no access to the underlying resource.
Parameters:
| Name | Type | Attributes | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
<optional> |
Properties
|
- Source:
Throws:
-
Will throw an error if failureFlash is used without flash middleware, failureFlash is used without failureRedirect, or originField is used without failureRedirect
- Type
- Error
Returns:
Express middleware
- Type
- ExpressMiddleware
Example
router.get('/admin', passwordless.restricted({ failureRedirect: '/login' }),
function(req, res) {
res.render('admin', { user: req.user });
});
sessionSupport() → {ExpressMiddleware}
By adding this middleware function to a route, Passwordless automatically restores
the logged in user from the session. In 90% of the cases, this is what is required.
However, Passwordless can also work without session support in a stateless mode.
- Source:
Throws:
-
Will throw an error no session middleware has been supplied
- Type
- Error
Returns:
Express middleware
- Type
- ExpressMiddleware
Example
var app = express();
var passwordless = new Passwordless(new DBTokenStore());
app.use(cookieParser());
app.use(expressSession({ secret: '42' }));
app.use(passwordless.sessionSupport());
app.use(passwordless.acceptToken());