@iamjs/express
This package contains the express middleware for iamjs a library for easy role and permissions management for your express application.
Installation
npm install @iamjs/core @iamjs/express
# or
yarn add @iamjs/core @iamjs/express
# or
pnpm add @iamjs/core @iamjs/express
# or
bun add @iamjs/core @iamjs/express
Usage
Authorization
You can use the ExpressRoleManager
to authorize a request in your express application by creating a new instance and using the check
method.
Example:
import { Role, Schema } from '@iamjs/core';
import { ExpressRoleManager } from '@iamjs/express';
import express from 'express';
const role = new Role({
name: 'role',
config: {
resource1: {
base: 'crudl'
},
resource2: {
base: 'cr-dl',
custom: {
'create a new user': false
}
}
}
});
const schema = new Schema({
roles: { role }
});
const roleManager = new ExpressRoleManager({
schema: schema,
onError(_err, _req, res, _next) {
res.status(403).send('Forbidden');
},
onSucess(_req, res, _next) {
res.status(200).send('Hello World from the success handler!');
}
});
const app = express();
app.get(
'/resource1',
roleManager.check({
resources: 'resource1',
actions: ['create', 'update'],
role: 'role',
strict: true
}),
(_req, res) => {
res.send('Hello World!');
}
);
Advanced Usage
By using the construct
option you can use the data from the request to build the role from its own permissions.
import { Role, Schema } from '@iamjs/core';
import { ExpressRoleManager } from '@iamjs/express';
import express from 'express';
const role = new Role({
name: 'role',
config: {
resource1: {
base: 'crudl'
},
resource2: {
base: 'cr-dl',
custom: {
'create a new user': false
}
}
}
});
const schema = new Schema({
roles : { role }
});
const roleManager = new ExpressRoleManager({
schema: schema,
onError(_err, _req, res, _next) {
res.status(403).send('Forbidden');
},
onSucess(_req, res, _next) {
res.status(200).send('Hello World from the success handler!');
}
});
const app = express();
const auth = async (req, res, next) => {
req.permissions = role.toObject();
next();
};
app.get(
'/resource1',
auth,
roleManager.check({
resources: 'resource1',
actions: ['create', 'rupdate'],
strict: true,
construct: true,
// get the role json or object from the request
data: async (req) => {
return req.permissions
}
}),
(_req, res) => {
res.send('Hello World!');
}
);
app.listen(3000, () => {
console.log('Example app listening at http://localhost:3000');
});
Success and Error Handling
You can pass onSuccess
and onError
handlers to the ExpressRoleManager
constructor to handle the success and error cases.
Example:
import { Role } from '@iamjs/core';
import { ExpressRoleManager } from '@iamjs/express';
import express from 'express';
const app = express();
const role = new Role({
name: 'role',
config: {
resource1: {
base: 'crudl'
},
resource2: {
base: 'cr-dl',
custom: {
'create a new user': false
}
}
}
});
const schema = new Schema({
roles : { role }
});
const roleManager = new ExpressRoleManager({
schema: schema,
onError(_err, _req, res, _next) {
res.status(403).send('Forbidden');
},
onSucess(_req, res, _next) {
res.status(200).send('Hello World from the success handler!');
}
});
app.get(
'/resource1',
roleManager.check({
resources: 'resource1',
actions: ['create', 'update'],
role: 'role',
strict: true
}),
(_req, res) => {
res.send('Hello World!');
}
);
app.listen(3000, () => {
console.log('Example app listening at http://localhost:3000');
});
Typescript Support
This package is written in typescript and has type definitions for all the exported types also the check
method accepts a generic type which can be used to define the type of the request or response object.
Example:
import { Role } from '@iamjs/core';
import { ExpressRoleManager } from '@iamjs/express';
import express from 'express';
const app = express();
const role = new Role({
name: 'role',
config: {
resource1: {
base: 'crudl'
},
resource2: {
base: 'cr-dl',
custom: {
'create a new user': false
}
}
}
});
const schema = new Schema({
roles : { role }
});
const roleManager = new ExpressRoleManager({
schema: schema,
onSuccess : <express.Request, express.Response>(req, res, next) => {
res.send('Hello World!');
},
onError: <express.Request, express.Response>(err, req, res, next) => {
console.error(err);
res.status(403).send('Forbidden');
},
});
const auth = async (req: express.Request, res: express.Response, next: express.NextFunction) => {
req.permissions = user.toObject();
next();
};
app.get('/post',
auth,
roleManager.check<express.Request, express.Response>({
resources: 'resource1',
actions: ['create', 'rupdate'],
strict: true,
construct: true,
// get the role json or object from the request
data: async (req) => {
return req.permissions
}
}),
(req, res) => {
res.send('Hello World!');
});
app.listen(3000, () => {
console.log('Example app listening at http://localhost:3000');
});
Save users activity
You can save user activity using the onActivity
method on the ExpressRoleManager
import { Role } from "@iamjs/core";
import { ExpressRoleManager } from "@iamjs/express";
import express from "express";
const app = express();
const role = new Role({
name: "role",
config: {
resource1: {
base: "crudl",
},
resource2: {
base: "cr-dl",
custom: {
"create a new user": false,
},
},
},
});
const schema = new Schema({
roles: { role },
});
const roleManager = new ExpressRoleManager({
schema: schema,
onError(_err, _req, res, _next) {
res.status(403).send("Forbidden");
},
onSucess(_req, res, _next) {
res.status(200).send("Hello World from the success handler!");
},
async onActivity(data) {
console.log(data);
},
});
app.get(
"/resource1",
roleManager.check({
resources: "resource1",
actions: ["create", "update"],
role: "role",
strict: true,
}),
(_req, res) => {
res.send("Hello World!");
}
);
app.listen(3000, () => {
console.log("Example app listening at http://localhost:3000");
});
The data object contains:
Name | Description |
---|---|
actions? | The action or actions that are authorized to be executed on the resource |
resources? | The resource or resources that are authorized to be accessed |
role? | The role that is used to authorize the request |
success? | The status of the request |
req? | The request object |