Groups

A FusionAuth Group serves two purposes.

First, a Group collects one or more users within a Tenant. You can find the members of a Group with the User Search API.

Second, a Group manages Application Role assignment. You can assign a Group roles from one or more Applications. Each member of the Group receives those roles for every Application the member has a registration for.

Core Concepts Relationships#

The following diagram shows how Groups relate to the other FusionAuth core concepts.

Examples#

Here are some examples of using Groups.

Grouping Users#

If you are performing educational marketing activities and driving self-service signups, you can pull the source of a signup off a URL parameter and place it into the user.data field using a custom registration form. On user creation, you could add them to a variety of Groups based on the attributes of the webinar using a webhook.

For example:

• Date of signup
• Online or offline presentation
• Presenter
• Version of webinar

You could then use these Groups for cohort analysis later to see which users best converted to paying customers.

This usage of Groups can be similarly performed by the user.data custom data fields. However, with this approach, each Group can have metadata in the group.data field that includes information about the Group and how and why users were placed in it. The use of a separate grouping object with its own metadata can be useful.

Assigning Roles#

You could create a Group called Admin, and assign this group the admin role from each of your applications.

A more detailed example:

Suppose the Pied Piper Application has two roles: admin and member. The Hooli Application has one role superadmin.

Richard has a registration in Pied Piper and Nelson has a registration in Hooli.

Finally, there's a group called Admin Group which has the application roles of admin from Pied Piper and superadmin from Hooli.

If you add Richard to the Admin Group, Richard receives the admin role in Pied Piper. Richard doesn't receive the superadmin role, because Richard has no registration for Hooli.

Group Membership In Tokens#

Sometimes you want membership information in an access token generated by a login event. A JWT Populate Lambda receives the user's group Ids in user.memberships, but not the group names.

To add group names, use Lambda HTTP Connect to call the Groups API from the lambda.

The following lambda adds the names of the user's groups to the access token. The user.memberships argument holds only group Ids, so the lambda calls the Groups API for the names. The lambda reads a FusionAuth API key from a lambda secret named fusionauth-api-key. Lambda secrets are available in FusionAuth 1.64.0 and later. The lambda calls the local FusionAuth HTTP port, 9012 by default, so the request doesn't leave the server. When the call fails, the lambda logs the error and issues the token with an empty groups claim.

// adds the names of the user's groups to the access token
function populate(jwt, user, registration, context) {
  var groupIds = user.memberships.map(function (membership) {
    return membership.groupId;
  });
  if (groupIds.length === 0) {
    jwt.groups = [];
    return;
  }

  var response = fetch('http://localhost:9012/api/group', {
    method: 'GET',
    headers: {
      'Authorization': context.services.secrets.get('fusionauth-api-key')
    }
  });

  // issue the token without groups instead of failing the login
  if (response.status !== 200) {
    console.error('Could not read groups. The Groups API returned status ' + response.status + '.');
    jwt.groups = [];
    return;
  }

  jwt.groups = JSON.parse(response.body).groups
    .filter(function (group) {
      return groupIds.indexOf(group.id) !== -1;
    })
    .map(function (group) {
      return group.name;
    });
}

Admin UI#

Create a Group#

Click on Settings -> Groups from the main menu to add a Group. At a minimum, you must provide a Name for the Group and the Tenant it belongs to.

You may apply Application roles from the various Applications in this Group's Tenant.

/admin/group/add

Form Fields#

Limits#

Groups can only contain Users, not other Groups.

Groups are always contained within a Tenant, and cannot span Tenants.