README
Express JWT Auth
Middleware for user authorization and authentication with JSON Web Token. Uses MongoDB for data storage.
The module is in early beta stage.
Features
- user signup
- user login
- profile edit
- password reset
- account removal
- keep alive for token renewal
Quick start
npm install express-jwt-auth
Example integration:
var express = require('express');
var app = express();
var http = require('http');
var server = http.Server(app);
var path = require('path');
var bodyParser = require('body-parser');
var settings = {
mongoconnection: 'mongodb://localhost:27017/dbname',
logFile: path.join(__dirname, 'authlogger.log'),
corsDomains: ['http://localhost:5000'],
// Nodemailer settings, used for resetting password
mailer: {
mailerFrom : 'your.mail@example.com',
mailerTitle : 'Password reset',
transporter : {
service: 'Gmail',
auth: {
user: 'your.mail@gmail.com',
pass: '<app_token>'
}
}
}
};
var auth = require('express-jwt-auth')(app, settings);
app.use(bodyParser.json());
app.get('/api/test', auth, function(req, res) {
res.send('Secured access.');
});
server.listen(3000);
Securing routes
express-jwt-auth is a middleware, meaning you can pass the module to express routing as an agrument, as in the integration example above: app.get('/api/test', auth, function(req, res) { ...
Options
Name | Default value | Description |
---|---|---|
mongoconnection |
- | MongoDB connection string, ex. mongodb://localhost:27017/my-notes . |
urlStrings |
{ signup: '/signup', login: '/login', remindpassword: '/remindpassword', resetpassword: '/resetpassword', checkauth: '/checkauth', keepalive: '/keepalive', editprofile: '/editprofile', removeaccount: '/removeaccount' } |
Object with url strings. |
removeCallback |
- | Execute a callback on account remove. The callback returns removed user id. |
logFile |
- | Log file name/path. |
tokenSecret |
53cr3t-h3re-p9t | String for salting token encryption. |
tokenExpire |
300 | Token expiration period in seconds. |
corsDomains |
- | Array with allowed domains. Ex. ['http://mydomain.com', 'http://example.com'] |
mailer |
- | Transport settings for nodemailer module. More details |
Secured requests
Secured requests must contain a header parameter with JSON Web Token string: Authorization:Bearer <JWT string>
API
signup
If the signup request is valid (payload parameters validated: username, email and password) it returns a json object: {token: <JWT string>}
Errors
If the payload data is invalid (username, email, password) the server returns a collection of error objects, for example: [{"param":"username","msg":"Username must be at least 4 characters long","value":"dd"},{"param":"password","msg":"Password must be at least 4 characters long","value":"ee"}]
with status code 400
.
In case of data conflict (existing username or email): [{"msg":"Email already exists","param":"email"},{"msg":"Username already exists","param":"username"}]
. Status code is 409
.
login
Successful login (request payload parameters: username and password) returns a json object: {token: <JWT string>}
Errors
Object: {"msg":"Unauthorized"}
. Status code 401
.
editprofile
If payload parameters are valid (username, email and optional password) retuns a json object: {token: <JWT string>}
. Updates password only if the password string is not empty.
Errors
The same as for signup
.
removeaccount
checkauth
Returns code 200 or 401 in case the token is not validated
keepalive
Should be send using intervals. Returns refreshed token: {token: <JWT string>}
.
remindpassword
The post data must contain email
and url
parameters. url
should be the domain of your service. For example for url set to http://example.com
a reset password link will be generated and sent to the user: http://example.com/resetpassword?token=<token_string>
.
If the payload email is validated sends an email with reset password link. Returns: {"msg":"new_password_sent"}
. Requires nodemailer transport settings.
Errors
[{"msg":"Email not found","param":"email"}]
. Status code 400
.
resetpassword
Sends a new password provided by user. Payload parameters: password string, reset token from query string parameter.
Tests
Run tests with npm test
.
Example Front-End implementation
Angularjs example can be found in a separate repository: https://github.com/baniol/angularjs-auth
Follow the instructions from the readme file.
License
Copyright (c) 2014 Marcin Baniowski http://baniowski.net