tachybase_todo/docs/en-US/api/acl/acl.md

ACL

Overview

ACL is the permission control module in NocoBase. After registering roles and resources in ACL and configuring corresponding permissions, you can authenticate permissions for roles.

Basic Usage

const { ACL } = require('@nocobase/acl');

const acl = new ACL();

// Define a role named member
const memberRole = acl.define({
  role: 'member',
});

// Grant the role of member list permission of the posts resource
memberRole.grantAction('posts:list');

acl.can('member', 'posts:list'); // true
acl.can('member', 'posts:edit'); // null

Concepts

• Role (ACLRole): Object that needs permission authentication.
• Resource (ACLResource)：In NocoBase ACL, a resource usually corresponds to a database table; it is conceptually analogous to the Resource in Restful API.
• Action: Actions to be taken on resources, such as create, read, update, delete, etc.
• Strategy (ACLAvailableStrategy): Normally each role has its own permission strategy, which defines the default permissions of the role.
• Grant Action: Call the grantAction function in ACLRole instance to grant access to Action for the role.
• Authentication: Call the can function in ACL instance, and return the authentication result of the user.

Class Methods

constructor()

To create a ACL instance.

import { ACL } from '@nocobase/database';

const acl = new ACL();

define()

Define a ACL role.

Signature

• define(options: DefineOptions): ACLRole

Type

interface DefineOptions {
  role: string;
  allowConfigure?: boolean;
  strategy?: string | AvailableStrategyOptions;
  actions?: ResourceActionsOptions;
  routes?: any;
}

Detailed Information

• role - Name of the role

// Define a role named admin
acl.define({
  role: 'admin',
});

• allowConfigure - Whether to allow permission configuration
• strategy - Permission strategy of the role
  • It can be a name of strategy in string, means to use a strategy that is already defined.
  • Or AvailableStrategyOptions means to define a new strategy for this role, refer to setAvailableActions().
• actions - Pass in the actions objects accessible to the role when defining the role, then call aclRole.grantAction in turn to grant resource permissions. Refer to aclRole.grantAction for details

acl.define({
  role: 'admin',
  actions: {
    'posts:edit': {}
  },
});
// Equivalent to
const role = acl.define({
  role: 'admin',
});

role.grantAction('posts:edit', {});

getRole()

Get registered role objects by role name.

Signature

• getRole(name: string): ACLRole

removeRole()

Remove role by role name.

Signature

• removeRole(name: string)

can()

Authentication function.

Signature

• can(options: CanArgs): CanResult | null

Type

interface CanArgs {
  role: string; // Name of the role
  resource: string; // Name of the resource
  action: string; // Name of the action
}

interface CanResult {
  role: string; // Name of the role
  resource: string; // Name of the resource
  action: string; // Name of the action
  params?: any; // Parameters passed in when registering the permission
}

Detailed Information

The can method first checks if the role has the corresponding Action permission registered; if not, it checks if the strategy and the role matches. It means that the role has no permissions if it returns null; else it returns the CanResult object, which means that the role has permissions.

Example

// Define role and register permissions
acl.define({
  role: 'admin',
  actions: {
    'posts:edit': {
      fields: ['title', 'content'],
    },
  },
});

const canResult = acl.can({
  role: 'admin',
  resource: 'posts',
  action: 'edit',
});
/**
 * canResult = {
 *   role: 'admin',
 *   resource: 'posts',
 *   action: 'edit',
 *   params: {
 *     fields: ['title', 'content'],
 *   }
 * }
 */

acl.can({
  role: 'admin',
  resource: 'posts',
  action: 'destroy',
}); // null

use()

Signature

• use(fn: any) Add middleware function into middlewares.

middleware()

Return a middleware function to be used in @nocobase/server. After using this middleware, @nocobase/server will perform permission authentication before each request is processed.

allow()

Set the resource as publicly accessible.

Signature

• allow(resourceName: string, actionNames: string[] | string, condition?: string | ConditionFunc)

Type

type ConditionFunc = (ctx: any) => Promise<boolean> | boolean;

Detailed Information

• resourceName - Name of the resource
• actionNames - Name of the resource action
• condition? - Configuration of the validity condition
  • Pass in a string to use a condition that is already defined; Use the acl.allowManager.registerCondition method to register a condition.

    acl.allowManager.registerAllowCondition('superUser', async () => {
      return ctx.state.user?.id === 1;
    });
    
    // Open permissions of the users:list with validity condition superUser
    acl.allow('users', 'list', 'superUser');
    

  • Pass in ConditionFunc, which can take the ctx parameter; return boolean that indicate whether it is in effect.

    // user:list accessible to user with ID of 1
    acl.allow('users', 'list', (ctx) => {
      return ctx.state.user?.id === 1;
    });
    

Example

// Register users:login to be publicly accssible
acl.allow('users', 'login');

setAvailableActions()

Signature

• setAvailableStrategy(name: string, options: AvailableStrategyOptions)

Register an available permission strategy.

Type

interface AvailableStrategyOptions {
  displayName?: string;
  actions?: false | string | string[];
  allowConfigure?: boolean;
  resource?: '*';
}

Detailed Information*

• displayName - Name of the strategy
• allowConfigure - Whether this strategy has permission of resource configuration; if set to true, the permission that requests to register as configResources resource in ACL will return pass
• actions - List of actions in the strategy, wildcard * is supported
• resource - Definition of resource in the strategy, wildcard * is supported