forio Toggle navigation

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

The options object passed to the F.manager.AuthManager() call can include:

  • account: 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).
  • userName: Email or username to use for logging in.
  • password: Password for specified userName.
  • project: The Project ID for the project to log this user into. Optional.
  • groupId: Id of the group to which userName belongs. Required for end users if the project is specified.

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.

Methods

login

Logs user in.

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

Parameters

  • options: Object (Optional) Overrides for configuration options. If not passed in when creating an instance of the manager (F.manager.AuthManager()), these options should include:

  • 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).

  • options.userName: string Email or username to use for logging in.

  • options.password: string Password for specified userName.

  • options.project: string (Optional) The Project ID for the project to log this user into.

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

logout

Logs user out by clearing all session information.

Example

  authMgr.logout();

Parameters

  • options: Object (Optional) Overrides for configuration options.

getToken

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

Example

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

Parameters

  • options: Object (Optional) Overrides for configuration options.

getUserGroups

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.

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

Parameters

  • params: Object Object with a userId and token properties.

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

  • 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 (Optional) Overrides for configuration options.

getCurrentUserSessionInfo

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.

Example

 var sessionObj = authMgr.getCurrentUserSessionInfo();

Parameters

  • options: Object (Optional) Overrides for configuration options.

addGroups

Adds one or more groups to the current session.

This method assumes that the project and group exist and the user specified in the session is part of this project and group.

Returns the new session object.

Example

 authMgr.addGroups({ project: 'hello-world', groupName: 'groupName', groupId: 'groupId' });
 authMgr.addGroups([{ project: 'hello-world', groupName: 'groupName', groupId: 'groupId' }, { project: 'hello-world', groupName: '...' }]);

Parameters

  • groups: object|array (Required) The group object must contain the project (Project ID) and groupName properties. If passing an array of such objects, all of the objects must contain different project (Project ID) values: although end users may be logged in to multiple projects at once, they may only be logged in to one group per project at a time.

  • group.isFac: string (optional) Defaults to false. Set to true if the user in the session should be a facilitator in this group.

  • group.groupId: string (optional) Defaults to undefined. Needed mostly for the Members API.