Opinionated authorization framework with Promises based on narando architecture.
npm install @narando/authorizationOpinionated authorization framework with Promises based on narando architecture.
You need to have nodejs and npm installed.
``bash`
$ npm install @narando/authorization
Activities take the form service:scope:method:item, eg.:api:articles:get:list. A Permission is an Activity that is linked to a user
and contains additional information:
`javascript`
// Permission
{
// Name of Activity
"name": "service:scope:method:item",
// Wether this permission only applies to objects that
// the user owns/has control of.
"onlyAssociated": true
}
To create an instance of the authorization module you have to invoke authorize
`javascript
import Authorization from "@narando/toolkit";
import model from "app/model";
// You can preconfigure options for the authorization.
// If you are in a specific express controller the scope
// of all checked permissions is usually the same, so you
// can set it once and then only need to overwrite it if it
// differs.
const auth = Authorization.authorize({ scope: "articles" });
// Now you can use the auth object to perform different kinds of
// authorization
await auth.action({
method: "get",
item: "list",
user: req.user,
});
// This will throw if the user does not have to required permissions for this activity
`
`javascript
// You can also use the express middleware to allow/deny access to parts of the interface
import express from "express";
const app = express();
app.use(
auth.middleware({
/ ... /
})
);
app.get("/restricted", (req, res) => {
/ ... /
});
// This will either call the next middleware if the user has sufficient permission
// or send a response with the appropriate HTTP response code associated to the
// thrown error as defined in @narando/errors
`
If you have a function and you want to restrict access to it, you can use the
decorator pattern.
To use it you have to have the babel plugin
babel-plugin-transform-decorators-legacy installed and configured.
`javascript`
@auth.decorate({
method: 'get',
item: 'list'
})
function getArticles(req) {
/ ... /
}
This will either throw on the invocation of the method if the user does not
have sufficient permissions, or call the decorated function if he does.
In some cases a black/white authorization strategy might be insufficient. A
user might have access to his own articles, but not to articles created by
other users. For these cases you can supply the auth method with a model class
and a model instance that will be queried for the association with the user.
These checks are only executed if the matching user permission has the flag
onlyAssociated: true. This allows administrators to bypass them, while normal
users will be stopped.
#### With a Model
When you have not yet found the instance of the requested resource, but want to
restrict access to the controller, you can set the model for the check in the
options:
`javascript`
@auth.decorate({
method: 'get',
item: 'list',
model: model.Article // { isAssociated: async ({ reqParams, user }) => boolean }
})
function getArticles(req) {
/ ... /
}
If the user has a permission with the right activity (api:articles:get:list
here) and a flag , the Authorization module will call theasync model.isAssociated({reqParams, user}) => boolean
method that you have
to implement. This method will get the path parameters and the user that is
making the request.
As the naming of the path parameters is up to the service it can be quite
inconsistent for different routes, so a one-size-fits-all implementation of
this variant is quite hard. The alternative is, to use the instance based
checks.
#### With an Instance
When you already have the instance, or you do not want to rely on the path
parameters you can can use the instance based association check. As with the
model based association check you have to supply the instance to the
authorization check:
`javascript
await auth.action({
method: 'put',
item: 'item',
user: req.user,
instance: article // { isAssociated: async ({ user }) => boolean }
})
article.update(newArticle);
`
Similar to the model based asssociation check, if the user has a permission
with the right activity (api:articles:put:item here) and a flagonlyAssociated: true, the Authorization module will call the methodasync instance.isAssociated({user}) => boolean that you have to implement.true
This method will receive the user that is making the request and is expected to
return if the user is associated and false otherwise.
#### Disable association checks
Association checks are enabled by default (disableAssociationCheck: false). If you wish to disable it you can pass disableAssociationCheck with a value of true via the options and it will ignore association checks. Examples are below.
`javascript`
@auth.decorate({
method: 'get',
item: 'list',
disableAssociationCheck: true
})
function getArticles(req) {
/ ... /
}
`javascript
await auth.action({
method: 'put',
item: 'item',
disableAssociationCheck: true
})
article.update(newArticle);
`
`javascript``
const auth = Authorization.authorize({
scope: "job",
disableAssociationCheck: true
});
As this package is part of the toolkit monorepo, please refer to the top-level
README to learn about hacking on this package.
* @narando/errors - Collection of semantic errors