Groups

Overview

There are a few reasons you may want to use a FusionAuth Group.

The first use is to logically group one or more users within a Tenant. Once a User is a member of a Group they may be identified as a member of the Group and retrieved using the User Search API.

The second reason you may use a Group is to manage Application Role assignment. A Group may be assigned roles from one or more Applications, a member of this Group will be dynamically assigned these roles if they have a registration for the Application.

Core Concepts Relationships

Below is a visual reminder of the relationships between FusionAuth’s primary 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, he will receive the role admin in Pied Piper, but not superadmin (because they aren’t registered for Hooli, so he can’t get the role for that application).

Group Membership In Tokens

Sometimes you want membership information in an access token generated by a login event. This data is not directly available in the lambda arguments.

However, you can do this by using Lambda HTTP Connect to request memberships using the Group API from within a JWT Populate Lambda. Here’s an example of such a lambda.

A lambda which adds claims based on a FusionAuth API.

function populate(jwt, user, registration) {
  var response = fetch("http://localhost:9012/api/group", {
    method: "GET",
    headers: {
      "Authorization": "bf69486b-4733-4470-a592-f1bfce7af580"
    }
  });

  if (response.status === 200) {
    // a successful response as defined in the Groups API
    var jsonResponse = JSON.parse(response.body);
    jwt.groups = jsonResponse.groups;
  } else {
    jwt.groups = [];
  }
}

This feature is only available in an Essentials or Enterprise plan. Please visit our pricing page to learn more.

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.

Form Fields

Limits

Groups can only contain Users, not other Groups.

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