Skip to content

Latest commit

 

History

History
245 lines (194 loc) · 7.25 KB

README.md

File metadata and controls

245 lines (194 loc) · 7.25 KB
Raw

Ngx Guardian logo

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

Using Angular CLI

ng add ngx-guardian

Using npm

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[] - ✔️ 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:

  1. setFromLocalStorage has priority over defaultRole strategie.
  2. If no setFromLocalStorage strategie is provided, default manager will be set with defaultRole strategie.
  3. 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

  1. Define your roles
// ngx-roles.ts

export enum NgxGuardianRole {
    ADMIN = 'ADMIN',
    DEFAULT = 'DEFAULT',
    ONLY_VIEW = 'ONLY_VIEW'
}
  1. Define your actions
// ngx-actions.ts

export enum NgxGuardianAction {
    CREATE = 'CREATE',
    READ = 'READ',
    UPDATE = 'UPDATE',
    DELETE = 'DELETE',
    APPROVE = 'APPROVE',
    REJECT = 'REJECT'
}
  1. 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: []
};
  1. 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