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);

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.

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.

Example: FormioAuthProvider.setForceAuth(true);

.setStates(anonState, authState);

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.

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".

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

.register(name, resource, path);

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.

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.

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

.setAnonRole(roleID);

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.

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

Example: FormioAuthProvider.setAnonRole('EXAMPLEOBJECTID');

.setAppUrl(url);

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.

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

Initializing FormioAuth

You need to run the init() method in order to initialize all of the authentications.

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

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