Repository files navigation

A simple unopinionated Vue plugin for managing user roles and permissions, access-control list (ACL) and role-based access control (RBAC).

• Vue Simple ACL
  • Table of Contents
  • Features
  • Installation
    • NPM
    • Yarn
    • CDN
  • Usage
    • Usage with Vue 3
    • Usage with Vue 2
    • ACL Rules File
    • Usage in component
      • hide modifier
      • disable modifier
      • readonly modifier
      • not modifier
      • any modifier
    • Using helper function in component
    • Using helper function insetup Vue's Composition API
    • Middleware for Vue Router
      • onDeniedRoute meta property
      • $from as valueonDeniedRoute
    • Vue Routermeta Properties
  • Semantic Alias directives and methods
  • Vue Simple ACL Options
  • TODO
  • 🤝 Contributing
  • ⭐️ Support
  • 📄 License

• Vue 2 and Vue 3 support
• Simple but robust and power ACL plugin
• Manage roles and permissions with ease.
• Lightweight (<3 kB zipped)
• Componentv-can directive
• Global$can helper function
• Sematic alias methods and directives of different verb for directive and helper function. E.gv-role,v-permission,$acl.permission(),$acl.anyRole(), etc.
• Middleware support forVue Router throughmeta property.
• Support user data from plain object, pinia/vuex store and asynchronous function.
• Reactive changes of abilities and permissions
• Define custom ACL rules
• Fully Typecript: The source code is written entirely in TypeScript.
• Fully configurable

npm install vue-simple-acl

yarn add vue-simple-acl

UNPKGJSDelivr

// src/main.js  OR  src/main.tsimport{createApp}from'vue'importAppfrom'./App.vue'importrouterfrom'./store';importstorefrom'./store';importaclfrom'./acl';// import the instance of the defined ACLconstapp=createApp(App);app.use(router);app.use(store);app.use(acl);// install vue-simple-aclapp.mount("#app");

In Vue 2, when using User data from reactive Store/Pinia/Vuex wrapped withcomputed() function, which is available in Vue 3 as module by default but not in Vue 2, make sure to install@vue/composition-api first and change the imported module to:import { computed } from '@vue/composition-api'

// src/main.js  OR  src/main.tsimportVuefrom'vue'importAppfrom'./App.vue'importrouterfrom'./router';importstorefrom'./store';importaclfrom'./acl';// import the instance of the defined ACLVue.config.productionTip=false;Vue.use(acl);// install vue-simple-aclnewVue({  router,  store,render:h=>h(App),}).$mount('#app')

For readability, it is recommend to defined your ACL rules in a separate file.

// src/acl/index.js  OR  src/acl/index.ts// Import router if you are using the middleware on Vue Routerimportrouterfrom"../router";// Import store if you are using reactive Store/Pinia/Vuex as User data sourceimportstorefrom"../store";// ----- VUE 3 Imports -----import{computed}from'vue';// For VUE 3import{createAcl,defineAclRules}from'vue-simple-acl';// ----- VUE 2 Imports -----importVuefrom'vue';importVueCompositionAPIfrom'@vue/composition-api';// Ensure this is installedVue.use(VueCompositionAPI);// VueCompositionAPI must be used as plugin before any function, otherwise see your console if warning/errprimport{computed}from'@vue/composition-api';// import computed functionimport{createAcl,defineAclRules}from'vue-simple-acl';// ---------------// The Vue Simple ACL option 'user' can be a user OBJECT, FUNCTION returning a user object// or an Asynchronous function returning a PROMISE of user object, suitable for performing fetch from API.// USER EXAMPLE 1: User {OBJECT}constuser={id:1,name:'Victory Osayi',is_editor:true,is_admin:false,// you can have role based permission list or access control list possibly from databasepermissions:['admin','owner','moderator','create-post','edit-post','delete-post']}// USER EXAMPLE 2: User object from a {FUNCTION} or computed property like from Pinia/Vuex Store// Suitable if you already has an existing logics authenticating and saving user data to Pinia/Vuex Storeconstuser2=computed(()=>store.state.auth.user);// USER EXAMPLE 3; User object from an Asynchronous {FUNCTION} / {PROMISE}:// Using Async/Promise requires instance of vue-router, the function will be auto hooked to beforeEach() peroperty of vue-routerconstuser3=()=>{constauthUserId=1;// ID of authenticated userreturnaxios.get(`api/users/${authUserId}`).then((response)=>response.data);}construles=()=>defineAclRules((setRule)=>{// setRule('unique-ability', callbackFunction(user, arg1, arg2, ...) { });// setRule(['unique-ability-1', 'unique-ability-2'], callbackFunction(user, arg1, arg2, ...) { });// Define a simple rule for ability with no argumentsetRule('create-post',(user)=>user.is_admin||user.is_editor);setRule('is-admin',(user)=>user.is_admin);setRule('is-editor',(user)=>user.is_editor);// Define a simple rule for ability with an argumentsetRule('edit-post',(user,post)=>user.id===post.user_id);setRule('delete-post',(user,post)=>{returnuser.id===post.user_id||user.is_admin;});// Define rule for array of multiple abilities that share same arguments and callback functionsetRule(['publish-post','unpublish-post'],(user,post)=>user.id===post.user_id);// Define rule for ability with multiple argumentssetRule('hide-comment',(user,post,comment)=>{returnuser.is_admin||user.id===post.user_id||(user.id===comment.user_id&&post.id===comment.post_id);});setRule('moderator',(user)=>user.permissions&&user.permissions.includes('moderator'));});constsimpleAcl=createAcl({  user,// short for user: user  rules,// short for rules: rules  router,// OPTIONAL, short for router: router// other optional vue-simple-acl options here... See Vue Simple ACL Options below});exportdefaultsimpleAcl;

Thev-can directive can be used in different ways and you can apply one or more modifiers that alters the behaviour of the directive.

<buttonv-can:create-post>Create Post</button><buttonv-can:edit-post="{ id: 100, user_id: 1, title: 'First Post' }">Edit</button><buttonv-can:edit-post="postData">Edit</button>

Alternative you can use the sematic alias;

<buttonv-permission:create-post>Create Post</button><buttonv-role:admin>Create Post</button><buttonv-role-or-permission="['admin', 'create-post']">Edit</button>

This is the default behaviour of thev-can directive, it remove the component or element from the DOM more likev-if.You're not required to apply it unless you want to explicitly state the behavior.

<buttonv-can:edit-post.hide="postData">Edit</button>

Thedisable modifier applies the disabled attribute to the tag, e.g. to disable a button or input that you are not allowed to use or edit respectively.

<buttonv-can:edit-post.disable="postData">Edit</button><inputv-can:edit-post.disable="post"v-model="postTitle"type="text">

Thereadonly modifier applies the readonly attribute to the tag, e.g. to make an input read only if you don't have permission to edit.

<inputv-can:edit-post.readonly="post"v-model="postTitle"type="text">

Thenot modifier reverses the ACL query. In this example only if you cannot delete the post the div element is shown.

<divv-can:delete-post.not="postData">You can not delete post created by you, ask admin for help.</div>

By defaultv-can directive with value that contains array of multiple abilities and ability arguments will be authorized if all specified abilities passes.Theany modifier authorized if atleast one or any of specified abilities and ability arguments passes.

<!-- Authorized if both abilities passes --><buttonv-can="['create-post', ['edit-post', post]]">Create Post</button><!-- Authorized if any of the abilities passes --><buttonv-can.any="[['edit-post', post], ['delete-post', post]]">Manage Post</button>

You can also use the helper function $can directly in component and #"auto" data-snippet-clipboard-copy-content="<form v-if="$can('edit-post', post)"> <input type="text" :value="post.title"> ...</form>">

<formv-if="$can('edit-post', post)"><inputtype="text":value="post.title">    ...</form>

if(this.$can('edit-post',post)){axios.put(`/api/posts/${post.id}`,postData)}

Using helper function insetup Vue'sComposition API

import{useAcl}from'vue-simple-acl';exportdefault{setup(){constacl=useAcl();if(acl.can('edit-post',post)){axios.put(`/api/posts/${post.id}`,postData)}if(acl.can('hide-comment',[post,comment])){// Execute this block if user can hide comment of a post}if(acl.can.not('edit-post',post)){// Execute this block if user can not edit post}if(acl.can.any(['is-admin','is-editor'])){// Execute this block if user is admin OR is editor}if(acl.can.any(['is-admin',['delete-post',post]])){// Execute this block if user is admin OR can delete post}// Get data of the defined ACL User being validatedconstuser=acl.user;constuser=acl.getUser();}}

Middleware forVue Router

constsimpleAcl=createAcl({  user,// short for user: user  rules,// short for rules: rules  router,// short for router: routeronDeniedRoute:'/unauthorized'// OR { path: '/unauthorized' } OR { name: 'unauthorized', replace: true} or '$from'});app.use(simpleAcl);

{path:'posts/create',name:'createPost',component:CreatePost,meta:{can:'create-post',onDeniedRoute:'/unauthorized'// value of onDeniedRoute option will be used if not set}}

{path:'posts/create',name:'createPost',component:CreatePost,meta:{can:['is-admin','create-post'],onDeniedRoute:{name:'unauthorizedPage',replace:true}}}

{path:'posts/create',name:'createPost',component:CreatePost,meta:{notCan:'moderator',onDeniedRoute:{name:'unauthorizedPage',replace:true}}}

{path:'posts/create',name:'createPost',component:CreatePost,meta:{anyCan:['is-admin','create-post'],onDeniedRoute:{name:'unauthorizedPage',replace:true}}}

{path:'posts/:postId',component:PostEditor,meta:{can:(to,from,can)=>{returnaxios.get(`/api/posts/${to.params.id}`).then((response)=>can('edit-post',response.data));},onDeniedRoute:'/unauthorized'}}

{path:'posts/:postId/publish',component:ManagePost,meta:{anyCan:(to,from,anyCan)=>{returnaxios.get(`/api/posts/${to.params.id}/publish`).then((response)=>anyCan(['is-admin',['edit-post',response.data]]));},onDeniedRoute:'/unauthorized'}}

{path:'posts/:postId/publish',component:ManagePost,meta:{anyCan:(to,from,anyCan,user)=>{returnaxios.get(`/api/users/${user.id}/posts/${to.params.id}/publish`).then((response)=>anyCan(['is-admin',['edit-post',response.data]]));},onDeniedRoute:'/unauthorized'}}

onDeniedRoute meta property

onDeniedRoute:{ path:'/login': replace:true}

$from as valueonDeniedRoute

onDeniedRoute:'$from'

Vue Routermeta Properties

Semantic Alias directives and methods

Vue Simple ACL Options

TODO

🤝 Contributing

⭐️ Support

📄 License