angular-restheart
AngularJS 1.x client module to handle RESTHeart API calls properly and easily.
Overview
This module contains the following services:
- RhAuth authentication service
- Rh Restangular service configured for RESTHeart
- FRh Restangular service configured for RESTHeart with full response enabled (response headers)
- RhLogic Restangular service for RESTHeart Application Logic resources
For more information on Restangular refer to its documentation
Build and release a new version of this library
Note: this section is for library's developers only.
- set the VERSION number in gulpfile.js then
gulp build
The gulp-bump plugin automatically updates the version number in both bower.json and package.json.
-
git tag
with the same VERSION -
git push
the new release.
Installation
Bower
bower install angular-restheart
Import the javascript component.
Inject into your App.
angular
Inject the two services into your Controller.
;
Configuration
You have to configure angular-restheart before using it.
setBaseUrl()
to set the base URL of RESTHeart.
setLogicBaseUrl(<logic_baseurl>)
to set the base URL of RESTHeart application logic handlers (usually /_logic but may differ). For more information refer to RESTHeart documentation
onForbidden(callback)
to set the callback function the be called on error 403 - Forbidden
onUnauthenticated(callback)
to set the callback function the be called on 401 - Unauthorized
onTokenExpired(callback)
to set the callback function the be called on 401 - Unauthorized
due to token expiration
The callback functions are passed two arguments: $location
and $state
, that can be used for redirection.
Also, in case of errors the rh_error
varible is set in the local storage:
rh_error: {"why": ["forbidded" | "expired" "not_authenticated"], "path": <path_where_error_occurred>, "state": <state_name_where_error_occurred>, "params": <state_params_object> }
Configuration Example
Authentication Flow
angular-restheart uses RESTHeart token-based authentication feature. For more information refer to RESTHeart documentation
The following sequence depicts the authentication flow:
Sign in
Client: Enter your email and password into the login form.
Client: On form submit call
RhAuth.signin()
with id and password.Client: Provide username and password credentials via the basic authentication method.
RestHeart Identity Manager (IDM): Verify the user identity: if not - return
401 Unauthorized
.RestHeart Access Manager (AM): Determine if the client is given the permission to execute it against the configured security policy:, if not - return
403 Forbidden
.RestHeart: Create an Auth Token and send it back to the client.
Client: Parse the token and save it to Local Storage for subsequent.
Sign out
Client: Call
RhAuth.signout()
with a boolean parameter.RestHeart: If
RhAuth.signout(true)
Remove Auth Token from database.Client: Remove token from Local Storage.
The RhAuth service
RhAuth service allows to easily authenticate a client. In case of authentication succedes, the authentication token generated by RESTHeart is saved in the session storage of the browser (with cookie fallback) and will be used by Rh* services to transparently manage authentication.
The two main public methods are signin()
and signout()
.
signin(id, password)
takes two input String parameters: id and password. It returns a promise that is resolved to true
if the authentication succedes and to false
otherwise.
Signin example
signout(invalidateToken)
clears the authentication token from the local storage. If invalidateToken
is true
it also makes a DELETE request to invalidate the authentication token from RESTHeart. Use false
if you don't want other user sessions to get signed out.
Signout example
Usage of Rh service
Rh
allows you to use Restangular properly configured to work with RESTHeart.