FormioAuth Provider

The FormioAuth Provider can be used to configure and enforce an authentication system for an angular application built with Form.io. It can be configured to enforce that all users accessing an application be authenticated, allow access to only a few states when not authenticated or allow non-authenticated users to access the application.

In addition it will set and maintain the authentication tokens and respond appropriately when authentication issues occur such as attempting to access an item that a user does not have access to or when a session token expires.

Configuring the Auth Provider

Configuration is done during your application's config phase. The FormioAuthProvider provides a number of functions that can be used to configure authentication.

angular.module('myapp')
  .config(function(FormioAuthProvider) {
    // Configure the Formio Authentication Provider.
    FormioAuthProvider.setForceAuth(true);
    FormioAuthProvider.setStates('auth.login', 'home');
    FormioAuthProvider.register('userLogin', 'user', 'user/login');
  });

.setForceAuth(forceAuth || allowedStates);

Name	Type	Description
forceAuth	Boolean	Set to true if you would like the user to only have access to approved states until they are authenticated. Otherwise, set it to false.
allowedStates	Array of Strings	A list of states that may be visited before authentication. Should include login and register states.
* The first parameter is either a boolean or array of strings.

This function will determine which mode the authentication system is running in. If set to false, anonymous users may access any state within the application. If set to an array of states, anonymous users may only access the states specified. If set to true, anonymous users can only access auth states.

Example: FormioAuthProvider.setForceAuth(true);

.setStates(anonState, authState);

Name	Type	Description
anonState	String	The login state. Defaults to "login.auth".
authState	String	The state the user is redirected to after login. Defaults to "home".

This function sets the two primary states for the authentication system. These are used to redirect users based on their authentication status. The anonState is where to send users when they aren't authenticated. This is typically a login and register page. The authState is where to redirect users after they login or register.

Example: FormioAuthProvider.setStates('auth.login', 'home');

.register(name, resource, path);

Name	Type	Description
name	String	The name of your login template. NOTE: Make sure to add an (name).html file to the views/user/ directory.
resource	String	(Optional) The resource that the login form is tied to. Set to null if you are tying the form to more than one resource. For example, if you had "employees" and "managers" logging in on the same form, you would set it to null. The form itself will confirm which resource the user is associated with.
path	String	(Optional) The state url that the login form will display when visible. If not specified it will default to the name parameter.
form	Object	(Optional) A form definition to use as the login form.
override	Boolean	(Optional) If a form is passed in along with a false value for override, it will be forced to use the default templates provided by ng-formio-helper.

The register function will register a resource that can be used to login and register. It will create ui-router states, templates and controllers that will manage the login and registration process.

Example: FormioAuthProvider.register('login', 'user', 'login');

.setAnonRole(roleID);

Name	Type	Description
role	Object Id	The role id of the anonymous role. This can be found in the project settings under roles.

The authentication system also manages an access system used by other providers within ngFormioHelper and if anonymous users are allowed to use the site, the access system needs to know what the anonymous RoleId is so that it can be used to check access for anonymous users. Use this function to set it.

Example: FormioAuthProvider.setAnonRole('EXAMPLEOBJECTID');

.setAppUrl(url);

Name	Type	Description
projectUrl	Url	The url of the project on form.io.

The access system will request a list of access permissions for the current user but in order to do so the project url needs to be set. Use this function to set the project url from form.io.

Initializing FormioAuth

You need to run the init() method in order to initialize the authentication and access system.

angular.module('myapp')
  .run(function(FormioAuth) {

    // Initialize the Form.io authentication provider.
    FormioAuth.init();
  });

Root Scope Functions and Objects

FormioAuth provides some root functions that can be used to customize functionality throughout your application based on a user's access. These can be called from within a controller using $rootScope or from within a template.

Please note that in order to use these access functions queries need to be made to the server so it is important to wait for a response. A $rootScope.whenReady promise is provided that will resolve after everything is ready.

$rootScope.user;

The currently logged in user. This should be treated as read only.

Example:

<div>Username: {{ user.data.name }}</div>

$rootScope.setUser(user);

Name	Type	Description
role	Object Id	The role id of the anonymous role. This can be found in the project settings under roles.

Set a user object as the logged in user. This will also manage localStorage and access tokens so it is important to use this function instead of setting $rootScope.user directly.

$rootScope.hasAccess(form, permissions);

The hasAccess function can be used to determine if a user has permission to perform actions on a form. Permissions are set on in the form's Access tab in the form.io portal.

Name	Type	Description
form	String	The name of the form to check against.
permissions	String || Array of Strings	Either a permission string or an array of permission strings to check.

Example: <div ng-if="hasAccess('myform', ['create_all', 'create_own'])">I can create!</div>

$rootScope.ifAccess(form, permissions);

Name	Type	Description
form	String	The name of the form to check against.
permissions	String || Array of Strings	Either a permission string or an array of permission strings to check.

A promise wrapper for hasAccess. This is useful for using inside of controllers as it will wait for the access callback response before checking access.

Example:

$rootScope.ifAccess('myform', ['create_all', 'create_own'])
  .then(function() {
    console.log('User has access!');
  });

$rootScope.logout();

A function that will logout the current user and clear all tokens and localStorage.

Example:

<a ng-click="logout()">Logout</a>