aurelia-permission
NPM packageWhat is aurelia-permission plugin?
aurelia-permission is a plugin for Aurelia to provide support of user authorization throughout the SPA app using defined user permissions.
Installation prerequisites
Obviously, you need to have installed NodeJs and Gulp. aurelia-permission was based on Aurelia plugin and requires only standard Aurelia libraries. It's highly recommended to use JSPM for package managment.
Installation
jspm install npm:aurelia-permission
Using Npm:
npm install aurelia-permission --save
Using typescript you can install definitions:
typings install github:matik12/aurelia-permission --save
Usage guide
Configure plugin in main configuration file & define avaiable permissions using PermissionStore
In your Aurelia configuration file(most commonly main file) add the plugin and provide configuration for user permissions :
; const sampleUser = id: 1 permissions: 'addUsers' 'deleteUsers' 'listUsers' const userPromise = { // Simulate promise getting user data including permissions from API ;}; { aureliause ; aureliastart; // If your landing default page needs permissions to show UI properly then // chain starting aurelia app with resolving user promise i.e as below // Thanks to that permissions will be defined before navigate to first page userPromise;} { configuration; userPromise ;}
Note: When listing 'only' acceptable permissions in route or in custom attribute the default logical operator is OR. This means that if any of the listed permissions is set then user is authorized to see / use element or navigate to particular route.
Default permission definition usage
When defining user permissions, it is possible to use default definition function instead of providing custom implementation as above. This default definition function simplly checks if particular permission exists in the supplied string array of user permissions. If this is the case, use code as shown below to simplify implementation and plugin configuration.
userPromise ;
Enum like permission object usage
It is possible to create enum like permission object with all permissions to use it in different authorization configurations instead of magic strings - string permission names, that are returned from API and can change. First define module (or scoped object, but module is recommended), which defines all application permissions as values of object properties as in sample below.
const UserPermission = AddUsers: 'Add_Users' DeleteUsers: 'Delete_Users' ListUsers: 'List_Users'
Then in plugin configuration in permission store leverage usage of definePermissionObject instead of definePermissions method as follows:
{ configuration; userPromise ;
Later on, use permission object properties i.e. when securing app routes
route: 'users' name: 'users' moduleId: 'users' nav: true title: 'Github Users' settings: permission: only: UserPermissionListUsers
Note: When permission object is set, then listed 'can' permission names in custom attribute -global-permission-show or -global-permission-enable / -global-permission-if or -global-permission-else must be permission object property names not values (actual API string permission names) i.e.
// correct usageCan add users! // incorrect usage in case of permission object setup, otherwise it is a correct permission nameCan add users!
This object method will define permissions for all values of properties.
Secure page routes using user permissions authorization
Using list of permissions and default redirect route if user is not authorized.
route: 'users' name: 'users' moduleId: 'users' nav: true title: 'Github Users' settings: permission: only: 'listUsers'
or setting redirectTo property to define route to redirect to in case user is not authorized.
route: 'users' name: 'users' moduleId: 'users' nav: true title: 'Github Users' settings: permission: only: 'listUsers' redirectTo: 'child-router'
Note: It is possible to set permission settings only on parent route to protect all child routes using the same set of permissions. What is more, this permission settings can be overwritten in child route. Child route can define permission settings and its permissions will be used, otherwise parent routes permissions will be processed. If no permissions are set, then access is granted.
Hide or disable elements in HTML templates based on user global permissions
Can add users!Can delete users!Can add or delete users!Can list users! // The following input element will be disabled when user has neither listUsers nor deleteUsers permissions // It is also possible to turn off permission check during bind lifecycle using check bindable binded from ViewModel, where some user defined conditions are met
Use AuthorizationService to implement custom application logic
; // Inject service via aurelia dependency injection { } // Then use it in the ViewModel code// i.e. define route in child router that will only be visible in navbar menu// when user has 'listUsers' permission defined route: 'child-router' name: 'child-router' moduleId: 'child-router' nav: thisauthorizationService title: 'Child Router'
Use PermissionFilter value converter for dynamic menu generation or to filter out route collections
Plugin provides value converter for filtering out menu items or any collection based on permission only settings property. This converter can be applied on child routers as well i.e. when you generate tabs based on child routes. Sample value converter usage is shown below.
API of plugin exported PermissionStore & AuthorizationService classes
static any; : void; : void; : void; : void; : boolean; : any;
: boolean;
Feature possible improvements
- Broadcast events on route navigation canceled - redirect and activating next route
- Support defining roles containing list of permissions
- Route permission configuration on parent route to protect all child routes with one definition