ngx-guardian

Logo designed by Yomissmar

Ngx Guardian

Empowering your Angular project using a powerful Permission Manager.
Explore Wiki »






Contributing · License

Ngx Guardian is a minimal, powerfull and easy configurable permission manager that grant the power to manage different roles in your Angular project.

Summary

• Installation
• Setup
• Manager preference setup
• Directives Usage
• Service Usage

Installation

Using Angular CLI

ng add ngx-guardian

Using npm

• npm install ngx-guardian --save

• Follow Setup & Permission Specification sections

Setup

In your App Module:

@NgModule({
    declarations: [. . .],
    providers: [. . .],
    imports: [
        NgxGuardianModule.forRoot({
            // Set up your managers here (see Permission specification)
            managers: [
                fooPermissionManager,
                otherFooPermissionManager,
                ...
            ],
            // Manager role to set its manager as default
            defaultRole: Role.ROLE_NAME,
            // Set a manager by localStorage value (see below)
            setFromStorage: true,
            // Navigate to this route if no role set
            unauthorizedRoute: '/no-auth',
            // Navigate to this route if user is no granted for route
            noGrantedRoute: '/no-granted'
        })
    ],
    exports: [. . .]
})
export class AppModule { }

You can delegate default manager setup to NgxGuardian setting a role in localStorage:

localStorage.setItem('ngx-guardian-role', 'ROLE_NAME');

forRoot() Config

Name	Type	Default	Required	Description
managers	NgxGuardianManager[]	-	:heavy_check_mark:	Permission Managers for application (with roles & actions over resources)
defaultRole	string	-	-	Default role to set its manager (if no provided, manager is disabled)
setFromStorage	boolean	false	-	Set role by localStorage value
unauthorizedRoute	string	"no-auth"	-	Route to navigate if no manager set
noGrantedRoute	string	"no-granted"	-	Route to navigate if user has no permissions

Manager preference setup

As there are different strategies to configure the default manager, the following priority has been established:

• setFromLocalStorage has priority over defaultRole strategie.
• If no setFromLocalStorage strategie is provided, default manager will be set with defaultRole strategie.
• If no set manager strategie is provided, the permission manager will be disabled.

Proposed files structure

├── src
    └── ngx-guardian
        ├── ngx-roles.ts
        ├── ngx-permissions.ts
        ├── ngx-resources.ts
        ├── ngx-config.ts
        ├── ngx-foo-manager.ts
        ├── ...
        └── ngx-other-foo-manager.ts

Permission specification

• Define your roles

// ngx-roles.ts

export enum NgxGuardianRole {
    ADMIN = 'ADMIN',
    DEFAULT = 'DEFAULT',
    ONLY_VIEW = 'ONLY_VIEW'
}

• Define your actions

// ngx-actions.ts

export enum NgxGuardianAction {
    CREATE = 'CREATE',
    READ = 'READ',
    UPDATE = 'UPDATE',
    DELETE = 'DELETE',
    APPROVE = 'APPROVE',
    REJECT = 'REJECT'
}

• Define your resources

// ngx-resources.ts

import { NgxGuardianResource } from 'ngx-guardian';

export const FOO: NgxGuardianResource = {
    name: 'FOO',
    routes: []
};

export const PIZZA: NgxGuardianResource = {
    name: 'PIZZA',
    routes: []
};

• Define your permission managers

//ngx-foo-manager.ts

import { NgxGuardianManager } from 'ngx-guardian';
import { NgxGuardianRole } from './ngx-role';
import { FOO, PIZZA } from './ngx-resources';
import { NgxGuardianAction } from './ngx-permissions';

export const defaultManager: NgxGuardianManager = {
    role: NgxGuardianRole.ADMIN,
    permissions: [
        {
            FOO,
            actions: [
                NgxGuardianAction.CREATE,
                NgxGuardianAction.READ
            ]
        },
        {
            resource: PIZZA,
            actions: [
                NgxGuardianAction.CREATE,
                NgxGuardianAction.READ
            ]
        }
    ]
}

Directives usage

The purpose of ngx-guardian directives is to simplify the logic of the templates designed to show, hide or modify the components or HTML code blocks according to permissions or user roles.

ShowIfGranted

This directive shows or hides a html block or component depending on whether a user has permission over a specific resource.

<!-- This component will be shown ONLY IF user has CREATE permission over PIZZA resource -->
<component-to-show-or-hide *ngxShowIfGranted="'CREATE - PIZZA'">
</component-to-show-or-hide>

<!-- This html block will be shown ONLY IF user has READ permission over PIZZA resource -->
<div *ngxShowIfGranted="'READ - PIZZA'">
    <p> Paragraph intended for users with READ permissions over pizza </p>
</div>

DisableIfNoGranted

This directive enable or disable a html block or component depending on whether a user has permission over a specific resource.

<!-- This component will be set disabled IF user HAS NOT CREATE permission over PIZZA resource -->
<component-to-enable-or-disable ngxDisableIfNoGranted="'READ - PIZZA'">
</component-to-enable-or-disable>

<!-- This html block will be set disabled IF user HAS NOT READ permission over PIZZA resource -->
<button ngxDisableIfNoGranted="'UPDATE - PIZZA'">
    Update pizza toppings
</button>

Service usage

The purpose of the Permission Service is to offer an interface for communication with the permission manager.

Method	Signature	Output	Description
isGranted	(action: string, resource: string)	boolean	If user can perform an action over resource
disableManager	-	-	Disable default permission manager
setManagerByRole	(role: string)	boolean	Set current manager for role provided
canNavigateTo	(url: string)	boolean	Returns if the user is granted to navigate to the path provided