Authorization Manager

The Authorization Manager provides an easy way to manage user authentication (logging in and out) and authorization (keeping track of tokens, sessions, and groups) for projects.

The Authorization Manager is most useful for team projects with an access level of Authenticated. These projects are accessed by end users who are members of one or more groups.

Using the Authorization Manager

To use the Authorization Manager, instantiate it. Then, make calls to any of the methods you need:

var authMgr = new F.manager.AuthManager({
   account: 'acme-simulations',
   userName: 'enduser1',
   password: 'passw0rd'
});
authMgr.login().then(function () {
   authMgr.getCurrentUserSessionInfo();
});

If you prefer starting from a template, the Epicenter JS Libs Login Component uses the Authorization Manager as well. This sample HTML page (and associated CSS and JS files) provides a login form for team members and end users of your project. It also includes a group selector for end users that are members of multiple groups.

Constructor options

Required?	Name	Type	Description
	groupId	string	Id of the group to which userName belongs. Required for end users if the project is specified.
	userName	string	Email or username to use for logging in.
	password	string	Password for specified userName.
	account	string	The account id. In the Epicenter UI, this is the Team ID (for team projects) or User ID (for personal projects). Defaults to undefined. If left undefined, taken from the URL.
	project	string	The project id. Defaults to undefined. If left undefined, parsed from the URL.
	token	string	For projects that require authentication, pass in the user access token (defaults to undefined). If the user is already logged in to Epicenter, the user access token is already set in a cookie and automatically loaded from there. (See more background on access tokens). @see Authentication API Service for getting tokens.
	transport	JQueryAjaxOptions	Options to pass on to the underlying transport layer. All jquery.ajax options are supported.
	server	object
	server.host	string	The value of host is usually the string api.forio.com, the URI of the Forio API server. This is automatically set, but you can pass it explicitly if desired. It is most commonly used for clarity when you are hosting an Epicenter project on your own server
	server.protocol	https / http	Defaults to https

Methods

login([options])

Logs user in.

Parameters

Required?	Name	Type	Description
	options	Object	Overrides for configuration options. If not passed in when creating an instance of the manager (F.manager.AuthManager()), these options should include:
Yes	options.account	string	The account id for this userName. In the Epicenter UI, this is the Team ID (for team projects) or the User ID (for personal projects).
Yes	options.userName	string	Email or username to use for logging in.
Yes	options.password	string	Password for specified userName.
Yes	options.groupId	string	The id of the group to which userName belongs. Required for end users if the project is specified and if the end users are members of multiple groups, otherwise optional.
	options.project	string	The Project ID for the project to log this user into.

Example

authMgr.login({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     userName: 'enduser1',
     password: 'passw0rd'
 }).then(function(statusObj) {
         // if enduser1 belongs to exactly one group
         // (or if the login() call is modified to include the group id)
         // continue here
     })
     .fail(function(statusObj) {
         // if enduser1 belongs to multiple groups,
         // the login() call fails
         // and returns all groups of which the user is a member
         for (var i=0; i < statusObj.userGroups.length; i++) {
             console.log(statusObj.userGroups[i].name, statusObj.userGroups[i].groupId);
         }
     });

logout([options])

Logs user out by clearing all session information.

Parameters

Required?	Name	Type	Description
	options	Object	Overrides for configuration options.

Example

authMgr.logout();

getToken([options])

Returns the existing user access token if the user is already logged in. Otherwise, logs the user in, creating a new user access token, and returns the new token. (See more background on access tokens).

Parameters

Required?	Name	Type	Description
	options	Object	Overrides for configuration options.

Example

authMgr.getToken()
    .then(function (token) {
        console.log('My token is ', token);
    });

getUserGroups(params[, options])

Returns an array of group records, one for each group of which the current user is a member. Each group record includes the group name, account, project, and groupId.

If some end users in your project are members of multiple groups, this is a useful method to call on your project's login page. When the user attempts to log in, you can use this to display the groups of which the user is member, and have the user select the correct group to log in to for this session.

Parameters

Required?	Name	Type	Description
Yes	params	Object	Object with a userId and token properties.
Yes	params.userId	String	The userId. If looking up groups for the currently logged in user, this is in the session information. Otherwise, pass a string.
Yes	params.token	String	The authorization credentials (access token) to use for checking the groups for this user. If looking up groups for the currently logged in user, this is in the session information. A team member's token or a project access token can access all the groups for all end users in the team or project.
	options	Object	Overrides for configuration options.

Example

// get groups for current user
var sessionObj = authMgr.getCurrentUserSessionInfo();
authMgr.getUserGroups({ userId: sessionObj.userId, token: sessionObj.auth_token })
    .then(function (groups) {
        for (var i=0; i < groups.length; i++)
            { console.log(groups[i].name); }
    });

// get groups for particular user
authMgr.getUserGroups({userId: 'b1c19dda-2d2e-4777-ad5d-3929f17e86d3', token: savedProjAccessToken });

isLoggedIn(none)

Helper method to check if you're currently logged in

Parameters

Required?	Name	Type	Description
Yes	none	none

Returns

Boolean - true if you're logged in

Example

var amILoggedIn = authMgr.isLoggedIn();

getCurrentUserSessionInfo([options])

Returns session information for the current user, including the userId, account, project, groupId, groupName, isFac (whether the end user is a facilitator of this group), and auth_token (user access token).

Important: This method is synchronous. The session information is returned immediately in an object; no callbacks or promises are needed.

Session information is stored in a cookie in the browser.

Parameters

Required?	Name	Type	Description
	options	Object	Overrides for configuration options.

Returns

Object - session information

Example

var sessionObj = authMgr.getCurrentUserSessionInfo();