Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »


0.0.6 • Public • Published


Build Status Coverage Status


$ npm install imicros-acl --save



  • a running Neo4j instance - refer to example.
  • imicros-groups service for managing the groups


The service expects user id and email to be set in ctx.meta data as follows:

ctx.meta.user = {
    id: 'unique ID of the user (number or string)',
    email: 'user@test.org'

Otherwise the service throws not authenticated error.

Usage acl

const { Acl } = require("imicros-acl");
await broker.createService(Acl, Object.assign({
                settings: { 
                    uri: process.env.NEO4J_URI || "bolt://localhost:7687",
                    user: process.env.NEO4J_USER || "neo4j",
                    password: process.env.NEO4J_PASSSWORD || "neo4j"


  • requestAccess { forGroupId } => { token }
  • verify { token } => { acl }
  • addGrant { forGroupId, ruleset } => { result } only for group admins
  • removeGrant { forGroupId } => { result } only for group admins


For ruleset language refer to imicros-rules-compiler.

The ruleset is called with the parameters

  • user: ctx.meta.user
  • ressource: parameter of call isAuthorized
  • action: parameter of call isAuthorized

Authorization logic

To get access for ressources of a group, an access token must be requested by calling acl.requestAccess. If the authenticated user in ctx.meta.user.id is member of the requested group forGroupId a token with unrestricted access is issued. If the authenticated user in ctx.meta.user.id is member of a group where grants are assigned to the requested group forGroupId a token with restricted access is issued. If the authenticated user in ctx.meta.user.id is neither a member nor a grant to one of his groups is assigned, no access token will be issued.

The retrieved access token must be delivered in the service call context under ctx.meta.acl.accessToken. This token is verified by the broker middleware.

The final authorization check is made in the mixin method isAuthorized. In case of restricted access the grant rulesets are called. If no grant solves to acl.result = 'allow' the access is denied.

Usage acl mixin

const { AclMixin } = require("imicros-acl");
const Service = {
    name: "AnyService",
    settings: {
        acl: {
            service: "acl"  // name of the acl service  
    mixins: [AclMixin],
    actions: {

Check authorization

// call method of acl mixin
await this.isAuthorized({ 
    ctx: ctx,               // context from action handler
    ressource: res,         // JSON representation of the ressource - attributes can be used in grant rules
    action: 'read'          // name of the called action or a specific command like read,write,update'

The original called action is also available in grant rules under environment.action.

Usage acl middleware

const { AclMiddleware } = require("imicros-acl");
broker = new ServiceBroker({
    logger: console,
    logLevel: "info",
    middlewares: [AclMiddleware]

The middleware wraps localAction and verifies a given accesstoken in ctx.meta.acl.accessToken by calling service acl.verify. If successful verified further acl parameter are set which are used by isAuthorized method of the mixin.


Neo4j - example docker-compose file

version: '3'


        image: neo4j
        container_name: neo4j
        # only necessary for access neo4j directly via webinterface 
        - "7474:7474"
        - "7687:7687"
        #  NEO4J_AUTH: 'none'
        - ./data:/data


npm i imicros-acl

DownloadsWeekly Downloads






Unpacked Size

72.5 kB

Total Files


Last publish


  • avatar