authentication and authorization module for angular apps
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
release
sample
src
test
.editorconfig
.gitignore
.travis.yml
CHANGELOG.md
Gruntfile.js
LICENSE
README.md
bower.json
package.json

README.md

#Visor

Authentication and authorization library for angular.js Build StatusDependency Status


Visor is an authentication and authorization framework for AngularJS.
It provides a convenient way to authenticate on startup and define which routes are accessible to whom.
Visor works with both ngRoute and ui-router.

Quick start

Get Visor:

  • download the release (or minified)
  • via Bower: by running $ bower install visor from your console
  • via NPM: by running $ npm install --save angular-visor from your console

Sample apps:

  • A sample app using ui-router can be found here (source)
  • A sample app using ng-route can be found here (source)

API documentation:

###Authenticate with visor:

    angular.module("yourModule",["visor","ngRoute"]).
        configure(function(visorProvider,$routeProvider){
            visorProvider.authenticate = function($http){
                return $http.get(<your authentication url>).then(function(res){return res.data;}) //returns user
            };
            $routeProvider.when("/private",{
                restrict: function(user){ return user && user.can_see_private}
            })
        });

Overview and Features

Visor provides two main features:

Authentication:

  • Visor allows you to stop routing until an authentication request is made.
  • Visor guarantees that authentication info is available (via visor.authInfo) before any restricted route is accessed.
  • If a client is not authenticated and tries to access an authenticated only route, it will be redirected to a designated login route.
  • After an unauthenticated client logsin/signsup, Visor makes sure to redirect the user back to the orignal route requested.

Authorization:

  • Visor works with both ngRoute and ui-router, and allows to idiomatically restrict access to routes in either modules.
  • Unauthorized users are sent to a dedicated "access denied" route.
  • Restrictions are simple functions defined on routes/states which can access the user's authentication info.

Usage

###Setting up the authenticate method

Visor requires that you define an authentication method that runs before restricted routes are accessed.
Visor exposes an authenticate method in it's provider:

    angular.module("yourModule",["visor"]).
        configure(function(visorProvider,$routeProvider){
            visorProvider.authenticate = function($http){
                return $http.get(<your authentication url>).then(function(res){return res.data;})
            };
        });

The authenticate method is dependency injected, and needs to return a promise.
The result from a successful promise will be sent to future restrict functions.

  • By default Visor authenticates when the page is loaded even if a non restricted route is accessed, you can instruct Visor to only authenticate when a restricted route is accessed by setting the `visorProvider.authenticateOnStartup" flag.

###Defining restrictions on routes

To define certain routes to be restricted to certain users, Visor requires a "restrict" attribute to exist inside the route or state.
That function will be called with the value returned from the authenticate promise and should return a boolean indicating if the routing should continue.
If a user was not authenticated the restrict function will be called with no values.

ngRoute:

    angular.module("yourModule",["ngRoute"]).
        configure(function($routeProvider){
            $routeProvider.when("/private",{ // will only be shown to users that have `can_see_private`
                restrict: function(auth){ return auth && auth.can_see_private}
            })
            .when("/only_not_authenticated",{ // will only be shown to users who are not authenticated
                restrict: function(auth){ return auth === undefined}
            })
            .when("/public",{}); // will be shown to any user
        });

ui-router:

    angular.module("yourModule",["ui.router"]).
        configure(function($stateProvider){
            $stateProvider.state("private",{ // will only be shown to users that have `can_see_private`
                restrict: function(auth){ return auth && auth.can_see_private}
            })
            .state("only_not_authenticated",{ // will only be shown to users who are not authenticated
                restrict: function(auth){ return auth === undefined}
            })
            .state("public",{}); // will be shown to any user
        });

     Visor also respects restrictions in parent states.

    angular.module("yourModule",["ui.router"]).
        configure(function($stateProvider){
            $stateProvider.state("private",{ // will only be shown to users that have `can_see_private`
                restrict: function(auth){ return auth && auth.can_see_private}
            })
            .state("only_not_authenticated",{ // will only be shown to users that have `can_see_private`
                parent:"private"
            })
            .state("admin",{ // will only be shown to users who have both `can_see_private` and `is_admin`
                parent:"private",
                restrict: function(auth){ return auth && auth.is_admin}
            });
        });

Visor provides two default restriction methods as constants:

  • authenticatedOnly - only users who are authenticated can see the route
  • notForAuthenticated - only users who aren't authenticated can see the route
    angular.module("yourModule",["ngRoute"]).
        configure(function($routeProvider,authenticatedOnly,notForAuthenticated){
            $routeProvider.when("/private",{ // will only be shown to users that are authenticated
                restrict: authenticatedOnly
            })
            .when("/only_not_authenticated",{ // will only be shown to users who are not authenticated
                restrict: notForAuthenticated
            })
            .when("/public",{}); // will be shown to any user
        });

Configuring actions on events

Visor defines the following situations that can be overriden:

  • An unauthenticated user tries to access a restricted route.

    • By default Visor will redirect to `/login' path.
    • The path can be overriden in visorProvider.loginRoute
    • The action taken when such an event occurs can be overriden in visorProvider.doOnNotAuthenticated
    • Visor adds a next parameter to the redirect to allow returning to the original path after a successful login.
    • You can instruct Visor to not add the next parameter by settings the visorProvider.shouldAddNext flag.
  • An authenticated user tries to access a restricted route.

    • By default Visor will redirect to `/access_denied' path.
    • The path can be overriden in visorProvider.notAuthorizedRoute
    • The action taken when such an event occurs can be overriden in visorProvider.doOnNotAuthorized
  • When a user is manually logged in.

    • By default if a next parameter exists in the url Visor will redirect to that path otherwise it'll redirect to `/' path.
    • The default path if no next is provided can be overriden in visorProvider.homeRoute
    • The action taken when such an event occurs can be overriden in visorProvider.doAfterManualAuthentication

###Login and Signup Visor needs to be notified when a user logs in to the application (as opposed to already being authenticated) in order for restrictions to work.
You inform visor when a user logs in by calling visor.setAuthenticated(authInfo).
The value sent to visor.isAuthenticated to be the same as the value returned in the authenticate promise.