https://github.com/concretesolutions/ng-security
A security module for AngularJS.
https://github.com/concretesolutions/ng-security
Last synced: about 1 year ago
JSON representation
A security module for AngularJS.
- Host: GitHub
- URL: https://github.com/concretesolutions/ng-security
- Owner: concretesolutions
- License: mit
- Created: 2015-08-19T18:01:36.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2017-04-18T18:37:20.000Z (about 9 years ago)
- Last Synced: 2025-03-24T05:43:36.384Z (about 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 104 KB
- Stars: 31
- Watchers: 16
- Forks: 4
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ngSecurity #
[![Build status][build-status-image]][build-status-url] [![Watch dependencies][dependencies-image]][dependencies-url] [![Watch dev dependencies][devDependencies-image]][devDependencies-url] [![NPM version][npm-version-image]][npm-url] [![NPM downloads][npm-downloads-image]][npm-url] [![MIT License][license-image]][license-url]
#### A security module for [AngularJS](http://angularjs.org). ####
## Install ##
Installing via [Bower](http://bower.io/):
```shell
$ bower install ngsecurity
```
Installing via [NPM](https://www.npmjs.org/):
```shell
$ npm install ngsecurity
```
## Get Started ##
Your setup should look similar to the following:
```javascript
/* 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');
});
});
```
```html
Login
User is authenticated
User is Anonymous
User is Administrator
```
```javascript
/* 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:
```javascript
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](http://jwt.io/) example:
```javascript
/* 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:
```javascript
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:
```javascript
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9", /* required */
"user": { /* optional */
"name": 'Administrator'
},
"permissions": [ /* optional */
'admin'
]
}
```
[JWT](http://jwt.io/) example:
```javascript
/* 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:
```javascript
{
"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="\" (Attribute only) ####
The directive only shows the HTML element if user has permission.
```html
Admin or Staff
Admin
```
#### ng-if-permission-model="\" (Attribute only) ####
The directive only shows the HTML element if user has permission specified on scope.
```javascript
angular
.module('myApp')
.controller(['$scope', '$security', function ($scope, $security) {
$scope.allPermission = [
'admin',
'staff'
];
$scope.adminPermission = 'admin';
}]);
```
```html
Admin or Staff
Admin
```
#### 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*.
```html
Admin or Staff
Admin and Staff
```
#### ng-enabled-permission="\" (Attribute only) ####
The directive sets the disabled attribute on the HTML element if user has permission.
```html
Add User
Remove User
```
#### ng-click-logout (Attribute only) ####
The directive logout current user.
```html
Logout
```
#### ng-bind-user="\" (Attribute only) ####
The directive replace the text content of the specified HTML element with the user data.
```html
```
#### ng-submit-login="\" (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.
```html
Success!
Username or password invalid!
Login
```
### Provider Options ###
```javascript
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'
}
});
}]);
```
[build-status-image]: https://travis-ci.org/concretesolutions/ng-security.svg
[build-status-url]: https://travis-ci.org/concretesolutions/ng-security
[dependencies-image]: https://david-dm.org/concretesolutions/ng-security.svg
[dependencies-url]: https://david-dm.org/concretesolutions/ng-security
[devDependencies-image]: https://david-dm.org/concretesolutions/ng-security/dev-status.svg
[devDependencies-url]: https://david-dm.org/concretesolutions/ng-security#info=devDependencies
[license-image]: http://img.shields.io/badge/license-MIT-blue.svg?style=flat
[license-url]: LICENSE
[npm-url]: https://npmjs.org/package/ngsecurity
[npm-version-image]: http://img.shields.io/npm/v/ngsecurity.svg?style=flat
[npm-downloads-image]: http://img.shields.io/npm/dm/ngsecurity.svg?style=flat