tutteli.auth for AngularJS
This module contains the following features:
##Installation
The code is quite small, so it is probably good enough to just copy the content of src/auth.js and src/auth-login-form.js manually (there are separate files for routing and http). Alternatively, you can install it with bower
bower install tutteli-angular-auth --save
Following an example how to include it
//use AuthService + form login + routing interception + http interception
angular.module('appFullAuth', ['tutteli.auth']);
//use only AuthService + form login
angular.module('app', ['tutteli.auth.login.form']);
//use routing interception + AuthService (login not possible)
angular.module('appWithUiRouting', ['tutteli.auth.routing']);
//use routing interception + AuthService + form login
angular.module('appWithUiRouting', ['tutteli.auth.routing',
'tutteli.auth.login.form']);
//use http interception + AuthService (login not possible)
angular.module('appInterceptHttp', ['tutteli.auth.http']);
AuthService
The AuthService works based on broadcasts, inspired by Gert Hengeveld's description and the following events are supported:
.constant('tutteli.auth.EVENTS', {
loginSuccess: 'tutteli-auth-login-success',
loginFailed: 'tutteli-auth-login-failed',
logoutSuccess: 'tutteli-auth-logout-success',
notAuthenticated: 'tutteli-auth-not-authenticated',
notAuthorised: 'tutteli-auth-not-authorised'
})
For convenience and maximum forward compatibility we recommend to use the constant 'tutteli.auth.EVENTS' to register for an event instead of using a hard-coded string. As an example:
.controller('tutteli.LoginCtrl',
['$rootScope', 'tutteli.auth.EVENTS',
function($rootScope, AUTH_EVENTS){
$rootScope.$on(AUTH_EVENTS.notAuthorised, function(event, url) {
alert('You are not authorised to visit ' + url);
});
}
]);
Following an example how the AuthService can be used to perform a log in:
.controller('LoginCtrl',
['$scope', 'tutteli.auth.AuthService',
function($scope, AuthService){
$scope.login = function(username, password) {
AuthService.login({
username: username,
password: password
/* add further data like csrf token etc. , ... */
});
};
}
]);
Whether the login was successful or not will be indicated with an event broadcasted on the $rootScope. Optionally you can perform an action directly in the controller by using the Promise returned by the login method of the AuthService. Notice, that the AuthService merely forwards the object passed to the login method via http POST to the specified value 'tutteli.auth.loginUrl' which can simply be redefined if desired:
//default value is based on the href attribute of the <base> tag + 'login'
//e.g., <base href="/app/"/> results in login url: /app/login
//this default value can be changed as follows:
angular.module('app',[])
//static url
.value('tutteli.auth.loginUrl', 'own/login/url')
//dynamic url
.factory('tutteli.authLoginUrl', function(){
return calculateLoginUrl();
});
Routing Interceptor
The routing interceptor requires ui.router to work and an additional data entry authRoles per route. Omitting the additional data entry corresponds to an empty list which indicates anonymous access. The AuthService does currently not support role hierarchies and hence one needs to indicate all roles, unless only authentication is required but not a special role. In this case USER_ROLES.authenticated can be used, 'is-authenticated' respectively.
Following an example:
.config(
['$locationProvider','$stateProvider', 'tutteli.auth.USER_ROLES',
function($locationProvider, $stateProvider, USER_ROLES) {
$locationProvider.html5Mode(true);
$stateProvider.state('login', {
url: '/login',
controller: 'tutteli.LoginCtrl',
templateUrl: 'login.tpl',
data: {
authRoles: [] //anonymous access
}
}).state('home', {
url: '/',
templateUrl: 'dashboard.html',
data: {
authRoles: [USER_ROLES.authenticated]
}
}).state('edit_user', {
url: '/users/:userId/edit',
templateUrl: 'edit_user.html',
data: {
authRoles: [USER_ROLES.admin],
userIdParamName: 'userId'
}
}).state('change_password', {
url: '/users/:userId/edit/password',
templateUrl: 'password.html',
data: {
authRoles: [USER_ROLES.noOne],
userIdParamName: 'userId'
}
});
}
]);
The above example also includes a state (edit_user) which either requires the role admin or a currently logged in user with the same user id as the one provided in the state's url. userIdParamName can be used for this purpose and must contain the name of the state parameter which contains the user id. In case only the current user shall be able to access a certain page (hence not even admins), one can use the special role noOne in combination with userIdParamName.
Http Interceptor
The http interceptor broadcasts events in case a 401 or 403 response returns from the server unless the 401 response follows a login attempt. The constant 'tutteli.auth.EVENTS' can be used to listen to the events. notAuthorised is broadcasted in case of 403 and notAuthenticated in case of a 401. See the example above in the AuthService section.
Copyright 2015 Robert Stoll rstoll@tutteli.ch
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.