SDK for Node.js
Roles and permissions
Decide what each of your users may do. A role is a name, like support, with the permissions it gives, like orders:refund. You choose both.
How it works
- You create roles in a user pool, each with a list of permissions.
- You give roles to users (a user can have several).
- When a user signs in, their roles and every permission those roles give go into their access token.
- Your routes check the token with
requirePermission()orrequireRole(). No call to the platform: the token says it all.
You can manage roles in the dashboard (User pools, then your pool) or from your code with the SDK, as below.
Create roles
const { SecureCloud } = require("@secure-cloud/sdk");
const cloud = new SecureCloud();
const users = cloud.userPool(process.env.SECURE_CLOUD_POOL_ID);
async function main() {
await users.createRole({
name: "support",
description: "Answers customers",
permissions: ["orders:read", "orders:refund"],
});
await users.createRole({
name: "admin",
description: "Runs the shop",
permissions: ["*"],
});
}
main();Run it once: node --env-file=.env setup-roles.js. A name that is taken throws CONFLICT.
| Name | Type | What it is |
|---|---|---|
name | string | Lowercase letters, digits, dots, colons, dashes or underscores. It can't be changed later. |
description | string (optional) | Who gets the role, for you and your team. |
permissions | string[] | Your own words, like orders:refund. orders:* gives everything under orders; * gives everything. |
Give roles to users
// For example when an admin promotes someone in your app.
await users.addRole(userId, "support");
// And to take it back:
await users.removeRole(userId, "support");Both are safe to repeat. A user can have up to 20 roles, and a pool up to 50.
Protect routes
const cookie = { cookie: "access_token" };
// Only users whose roles give this permission.
app.post("/orders/:id/refund", users.requirePermission("orders:refund", cookie), async (req, res) => {
await refundOrder(req.params.id, req.user.id);
res.json({ refunded: true });
});
// Only users with this role.
app.get("/admin", users.requireRole("admin", cookie), (req, res) => {
res.send("Welcome, admin");
});Signed out users get a 401, and signed in users without the permission a 403. Both are JSON answers, and your route never runs.
Check in your own code
Inside a route, req.user has the user's roles and permissions. hasPermission() understands the wildcards for you.
const { hasPermission } = require("@secure-cloud/sdk");
app.get("/orders/:id", users.requireUser(cookie), async (req, res) => {
const order = await findOrder(req.params.id);
const mine = order.customerId === req.user.id;
if (!mine && !hasPermission(req.user, "orders:read")) {
return res.status(404).json({ message: "No such order" });
}
res.json(order);
});Manage roles from code
| Name | Type | What it is |
|---|---|---|
listRoles() | Role[] | Every role in the pool, with how many users have it. |
createRole({ name, description, permissions }) | Role | Creates a role. |
getRole(name) | Role | One role. |
updateRole(name, { description, permissions }) | Role | Changes a role; its users get the new permissions in their next token. |
deleteRole(name) | nothing | Deletes a role and takes it from its users. |
addRole(userId, role) | PoolUser | Gives a user a role. |
removeRole(userId, role) | PoolUser | Takes a role from a user. |
requireRole(role, { cookie }) | middleware | Lets only users with the role through. |
requirePermission(permission, { cookie }) | middleware | Lets only users with the permission through. |
hasPermission(user, permission) | boolean | Checks a permission, wildcards included. |