ngsecurity v1.6.2
ngSecurity
A security module for AngularJS.
Install
Installing via Bower:
$ bower install ngsecurityInstalling via NPM:
$ npm install ngsecurityGet Started
Your setup should look similar to the following:
/* file: app.js */
angular
.module('myApp', ['ngSecurity'])
.config(['$httpProvider', function ($httpProvider) {
$httpProvider.interceptors.push('$securityInterceptor');
}])
.run(function ($rootScope) {
$rootScope.$on('unauthenticated', function () {
alert('redirect to login');
});
$rootScope.$on('permissionDenied', function () {
alert('redirect to permission denied');
});
});<!-- file: index.html -->
<!DOCTYPE html>
<html ng-app="myApp">
<body>
<form ng-submit-login="/auth/login">
<input type="text" name="username" />
<input type="password" name="password" />
<button type="submit">Login</button>
</form>
<div ng-if-authenticated>
User is authenticated
</div>
<div ng-if-anonymous>
User is Anonymous
</div>
<div ng-if-permission="admin">
User is Administrator
</div>
<script src="app.js"></script>
</body>
</html>/* POST /api/auth response */
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9", /* required */
"user": { /* optional */
"name": 'Administrator'
},
"permissions": [ /* optional */
'admin'
]
}API
Service Methods
login(token: String, [user: Object, permissions: Array]) Simple strategy
Authenticate a user with token. Data and permissions are optional.
Simple example:
angular
.module('myApp')
.controller(['$scope', '$http', '$security', function ($scope, $http, $security) {
$scope.username = 'admin';
$scope.password = 'admin';
$scope.authenticate = function () {
$http.post('/api/auth', {
username: $scope.username,
password: $scope.password
}).success(function (data) {
$security.login(data.token, data.user, data.permissions);
});
}
}]);login(token: String, permissions: Array) JWT strategy
Authenticate a user with token. Permissions are optional.
JWT example:
/* file: app.js */
angular
.module('myApp')
.config(['$httpProvider', '$securityConfigProvider', function ($httpProvider, $securityConfigProvider) {
$httpProvider.interceptors.push('$securityInterceptor');
$securityConfigProvider.configure({
strategy: 'jwt',
});
}])
.controller(['$scope', '$http', '$security', function ($scope, $http, $security) {
$scope.username = 'admin';
$scope.password = 'admin';
$scope.authenticate = function () {
$http.post('/api/auth', {
username: $scope.username,
password: $scope.password
}).success(function (data) {
$security.login(data.token, data.permissions);
});
}
}]);loginByUrl(url: String, data: Object)
Use resource for authenticate user. The service should return a response compatible. The return is a promise.
Simple example:
angular
.module('myApp')
.controller(['$scope', '$security', function ($scope, $security) {
$scope.username = 'admin';
$scope.password = 'admin';
$scope.authenticate = function () {
$security.loginByUrl('/api/auth', {
username: $scope.username,
password: $scope.password
}));
}
}]);Compatible API response:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9", /* required */
"user": { /* optional */
"name": 'Administrator'
},
"permissions": [ /* optional */
'admin'
]
}JWT example:
/* file: app.js */
angular
.module('myApp')
.config(['$httpProvider', '$securityConfigProvider', function ($httpProvider, $securityConfigProvider) {
$httpProvider.interceptors.push('$securityInterceptor');
$securityConfigProvider.configure({
strategy: 'jwt',
});
}])
.controller(['$scope', '$security', function ($scope, $security) {
$scope.username = 'admin';
$scope.password = 'admin';
$scope.authenticate = function () {
$security.loginByUrl('/api/auth', {
username: $scope.username,
password: $scope.password
}));
};
}]);Compatible API response:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiQWRtaW5pc3RyYXRvciJ9.cwtcdrm6c5fXBdnhzkFnlXmvvsRY7xB6YsKrLE_phm4", /* required */
}logout()
User logout and remove session user data.
hasPermission(permission: String)
Check if user has permission.
hasAllPermission(permissions: Array)
Check if user has all permission of array.
hasAnyPermission(permissions: Array)
Check if user has any permission of array.
isAuthenticated()
Check if user is authenticated.
getUser()
Get session user data.
getPermissions()
Get session user permissions.
Directives
ng-if-authenticated (Attribute only)
The directive only shows the HTML element if user is authenticated.
ng-if-anonymous (Attribute only)
The directive only shows the HTML element if user not is authenticated.
ng-if-permission="\<permission: String>" (Attribute only)
The directive only shows the HTML element if user has permission.
<div ng-if-permission="admin,staff">
<p>Admin or Staff</p>
<div ng-if-permission="admin">
<p>Admin</p>
</div>
</div>ng-if-permission-model="\<permission: Any>" (Attribute only)
The directive only shows the HTML element if user has permission specified on scope.
angular
.module('myApp')
.controller(['$scope', '$security', function ($scope, $security) {
$scope.allPermission = [
'admin',
'staff'
];
$scope.adminPermission = 'admin';
}]);<div ng-if-permission-model="allPermission">
<p>Admin or Staff</p>
<div ng-if-permission-model="adminPermission">
Admin
</div>
</div>ng-permission-type="ALL|ANY" (Attribute only)
The auxiliary directive for ng-if-permission, ng-if-permission-model and ng-enabled-permission, it determine the validation method.
The value default is ANY.
<div ng-if-permission="admin,staff" ng-permission-type="ANY">
<p>Admin or Staff</p>
</div>
<div ng-if-permission="admin,staff" ng-permission-type="ALL">
<p>Admin and Staff</p>
</div>ng-enabled-permission="\<permission: String>" (Attribute only)
The directive sets the disabled attribute on the HTML element if user has permission.
<button ng-enabled-permission="admin,staff">
Add User
</button>
<button ng-enabled-permission="admin">
Remove User
</button>ng-click-logout (Attribute only)
The directive logout current user.
<button ng-click-logout>
Logout
</button>ng-bind-user="\<attribute: String>" (Attribute only)
The directive replace the text content of the specified HTML element with the user data.
<div ng-bind-user="name">
<!-- render user name -->
</div>ng-submit-login="\<url: String>" (Attribute only)
The directive login user when submit form. It calls back ng-login-success when success to login, and calls back ng-login-error when fail to login.
<form ng-submit-login="/api/auth" ng-login-success="success($response)" ng-login-error="error($response)">
<div ng-show-login-success> <!-- show the HTML element when login is successful -->
<p>Success!</p>
</div>
<div ng-show-login-error> <!-- show the HTML element when login failed -->
<p>Username or password invalid!</p>
</div>
<input type="text" name="username" />
<input type="password" name="password" />
<button type="submit">Login</button>
</form>Provider Options
angular
.module('myApp')
.config(['$securityConfigProvider', function ($securityConfigProvider) {
$securityConfigProvider.configure({
strategy: 'simple', /* Validation method. Examples: 'jwt' */
token: {
header: 'Authorization', /* request header name intercepted */
prefix: ''
},
storageName: {
token: 'ng-security-authorization',
user: 'ng-security-user',
permissions: 'ng-security-permissions'
},
responseErrorName: { /* the name for broadcast of request error intercepted */
401: 'unauthenticated',
403: 'permissionDenied'
}
});
}]);