This middleware ensures that a user is authorized. If the user is unauthorized, the request returns a JSON error by default or redirects the user with additional configuration.
Yarn
$ yarn add connect-ensure-authorization
NPM
$ npm install connect-ensure-authorization
In this example, an application has a todos API endpoint. A user must be authorized before accessing this endpoint.
const express = require('express');
const { ensureScope } = require('connect-ensure-authorization');
const app = express();
// req.user should be like:
// {
// username: 'bob', <-- dummy data
// fullName: 'Bob', <-- dummy data
// scopes: ['todos:read'] <-- used for scope checking
// }
app.get('/api/todos', ensureScope('todos:read'), (req, res) => {
res.json([
{
text: 'First todo',
completed: false,
},
{
text: 'Second todo',
completed: true,
}
]);
});If a user is not authorized when attempting to access this API, the request will return the default 403 status code with the default message "Forbidden".
The following ensure functions are available:
| Function | User property |
|---|---|
ensureScope |
scopes |
ensurePermission |
permissions |
ensureRole |
roles |
ensureGroup |
groups |
All functions will check its corresponding user property. The user property should contain an array with strings. The ensure function does an Array.includes check. This default implementation can be modified to your custom requirement.
The ensure implementation can be overwritten with a custom implementation. This function must return a Promise or a Boolean.
const express = require('express');
const {
initialize: initializeAuthorization,
ensureScope
} = require('connect-ensure-authorization');
const app = express();
const onEnsureScope = ({ user, scope }) => new Promise((resolve, reject) => {
if (user.scopes.includes(scope)) {
resolve();
} else {
reject();
}
});
initializeAuthorization({ onEnsureScope });
app.get('/api/todos', ensureScope('todos:read'), (req, res) => {
res.json([
{
text: 'First todo',
completed: false,
},
{
text: 'Second todo',
completed: true,
}
]);
});The other ensure implementations are also supported to be overwritten (by passing onEnsurePermission, onEnsureRole and onEnsureGroup).
The middleware can be configured to return another status code and/or message when unauthorized.
const express = require('express');
const { initialize: initializeAuthorization } = require('connect-ensure-authorization');
const app = express();
initializeAuthorization({
statusCode: 418, // default = 403
message: 'I\'m a teapot!', // default = "Forbidden"
});
app.get('/api/todos', ensureScope('todos:read'), (req, res) => {
res.json([
{
text: 'First todo',
completed: false,
},
{
text: 'Second todo',
completed: true,
}
]);
});The following example redirects to /forbidden instead of returning a JSON message.
const express = require('express');
const { initialize: initializeAuthorization } = require('connect-ensure-authorization');
const app = express()
initializeAuthorization({
redirectTo: '/forbidden', // default = null
});
app.get('/api/todos', ensureScope('todos:read'), (req, res) => {
res.json([
{
text: 'First todo',
completed: false,
},
{
text: 'Second todo',
completed: true,
}
]);
});If you are using Passport, this defaultly sets the req.user after logging in. This can be modified to for example req.account.
const express = require('express');
const { initialize: initializeAuthorization } = require('connect-ensure-authorization');
const app = express()
initializeAuthorization({
userProperty: 'account', // default = "user"
});
// req.account should be like:
// {
// accountName: 'bob', // dummy data
// fullName: 'Bob', // dummy data
// scopes: ['todos:read'] <-- used for scope checking
// }
app.get('/api/todos', ensureScope('todos:read'), (req, res) => {
res.json([
{
text: 'First todo',
completed: false,
},
{
text: 'Second todo',
completed: true,
}
]);
});Take a look at the integration test for some inspiration.
I have also created a single file example repository using this module: https://github.com/allardvanderouw/express-api-passport-local-mongo-session-example/blob/master/server.js