egg-zrole

Install

$ npm i egg-zrole --save

Usage

// {app_root}/config/plugin.js
exports.zrole = {
  enable: true,
  package: 'egg-zrole',
};

Configuration

// {app_root}/config/config.default.js
exports.zrole = {
  useAdapter: false,
  useAnonymous: false,
  usePolicyInit: false,
  useCustomResponse: false,
  model: '/example/zrole_model.conf',
  policy: '/example/zrole_policy.csv',
  adapterConfig: () => {},
  getUser: (ctx) => {},
  initPolicy: () => {},
  customResponse: (ctx) => {},
  useAutoMiddleware: true,
  useSuperManage: 'admin'
};

Tips:

• After v1.0.5 you don't need to add the zrole to middleware.
• You must set the model path; When you don't use the adapter, you also need to set policy path.
• If your userinfo not in the Authorization, you should use getUser method to set how to get userinfo that can check the user role.If don't set the getUser method, it will jump.
• If use some casbin adapter, you need make useAdapter to true, then config the adapter, use adapterConfig method.
• If you need to init the policy, you can set usePolicyInit to true, and use initPolicy method to set role.
• If you need to custom your response, when 403; You can set useCustomResponse to true, and use customResponse method to custom the response.
• If you need to use default anonymous role, you can set useAnonymous to true.
• In v1.3.0, you can set useAutoMiddleware to false (default is true), then the zrole middleware will not add to your middleware array, you need to write middleware yourself.
• In v1.5.0, you can set super manage name to jump role check.
• After v2.0.2, support the keyMatch5 matcher.
• In v3.0.0, only support Nodejs v16.0.0+

see config/config.default.js for more detail.

Example

Details Project Later

Now, You can see test/fixtures, there are two example

1.test/fixtures/zrole-sequelize-test.

this test project, show the following features: 1.sequelize adapter; 2.init policy

• Use Sequlize and MySQL to control permission, in controller file, you can see this.app.zrole.addPolicy('xdd', '/', 'GET'), it test the policy's dynamic addition; and you need to set useAdapter to true;
• The casbin sequelize adapter, we use casbin-sequelize-adapter, about it, you can see https://github.com/node-casbin/sequelize-adapter
• It will auto create the database that name is casbin, when you don't set the database, and don't set SequelizeAdapter.newAdapter second params to ture
• If you want to use own database, you can set adapterConfig:

// example config.default.js
exports.zrole = {
  useAdapter: true,
  usePolicyInit: true,
  model: './example/zrole_model.conf',
  policy: './example/zrole_policy.csv',
  getUser: ctx => {
    if (ctx.headers.authorization) {
      return ctx.headers.authorization;
    }
    return null;
  },
  adapterConfig: async () => {
    const connect = await SequelizeAdapter.newAdapter(
      {
        host: 'localhost',
        port: 3306,
        database: 'test',
        username: 'root',
        password: 'root',
        dialect: 'mysql',
      },
      true
    );
    return connect;
  },
  initPolicy: zrole => {
    zrole.addPolicy('xdd', '/', 'GET');
    zrole.addPolicy('xdd', '/remove', 'GET');
  },
};

2.test/fixtures/zrole-test.

this test project, show the following features: 1.anonymous; 2.custom response; 3.multi roles check;4.super manage

model and policy use the fixed file If you set useAnonymous to true, the request that has no header(Authorization) will be the anonymous user. It will access the anonymous api, like,

p, anonymous, /anonymous, GET

// example
exports.zrole = {
  useAnonymous: true,
  useCustomResponse: true,
  model: './example/zrole_model.conf',
  policy: './example/zrole_policy.csv',
  getUser: ctx => {
    if (ctx.headers.authorization) {
      return ctx.headers.authorization;
    }
    return null;
  },
  customResponse: ctx => {
    ctx.status = 403;
    ctx.body = 'Your do not has permission to access';
  },
  useSuperManage: 'admin'
};

3.test/fixtures/zrole-no-auto-add-middleware-test.

this test project, show the following features: 1.use custom middleware

// example
exports.zrole = {
  useAutoMiddleware: false,
  model: './example/zrole_model.conf',
  policy: './example/zrole_policy.csv',
};

Questions & Suggestions

Please open an issue here.

License

MIT