Last updated

Getting started with account hierarchies

An account hierarchy is a system representing relationships between entities in an organization, including parent-child structures or multiple nested layers. This structure helps manage complex setups, improving communication, efficiency, and accountability.

With Hierarchies (Sub-account Management), you can create parent accounts with nested sub-accounts. Users can belong to any tenant or to a tenant and its subtenants.

While both hierarchies and multitenancy manage multiple entities, they have distinct purposes. Multitenancy serves multiple tenants from a single software instance, each with isolated data and configurations. Hierarchies, on the other hand, manage relationships and dependencies within a single tenant, providing granular control and resource allocation.

In Frontegg, users main parent account can create and manage sub-accounts within a hierarchy, offering more control over their account structure—ideal for complex setups or reselling scenarios. This is provided from All Accounts section under Frontegg's self-service portal.



Prerequisites

Note that the following versions are required to use the feature:

@frontegg/react@5.0.44
@frontegg/angular@5.35.0
@frontegg/vue@2.0.40
@frontegg/nextjs@7.0.14\


Sub-accounts management

Step:1 Enabling sub-account management on an account

Management → Accounts → [ACCOUNT] → Settings → Sub-account management toggle.


multi-apps-1

Step 2: Assigning permissions

To access the All Accounts tab in the self-service portal, users must be assigned specific roles with corresponding [Permissions]:

  1. Read access to sub-accounts:
    To view the "All Accounts" tab, users must have the role that grants them the "Read sub-accounts" permission: fe.account-hierarchy.read.subAccount. This permission allows them to view sub-account information.

  2. Create or update sub-accounts:
    If users need to create or update sub-accounts, they should be assigned a role with the "Create or update sub account" permission: fe.account-hierarchy.write.subAccount. This permission enables users to add new sub-accounts or modify existing ones.

  3. Delete sub-accounts:
    To delete sub-accounts, users must have a role with the "Delete sub-accounts" permission: fe.account-hierarchy.delete.subAccount. With this permission, users can remove unwanted sub-accounts from the system.

  4. Grant access to sub-accounts:
    If users need to provide access to sub-accounts within the account hierarchy, they should be assigned a role with the "Give access to sub-accounts" permission: fe.account-hierarchy.write.subAccountAccess. This permission allows users to assign access rights to other users for specific sub-accounts.

By ensuring users have the appropriate roles and permissions, you can control their access levels and actions within the self-service portal effectively.

Once the toggle for sub-account management is enabled and the relevant admin roles are assigned with the above permissions - an All Accounts section will appear in the end user's self-service menu.


multi-apps-1

Sub-accounts self-service

The self-service portal allows end users to self-manage tenant access, create sub-accounts, manage roles, and more. Once sub-account management is enabled, users can access a dedicated Managed section within their All Accounts menu.

When viewing All Accounts, users can see their account hierarchy in 2 views: Table and Graph.

In the table view, your main account is listed at the top, followed by all sub-accounts. The layout includes key details like account names, user counts, and creation dates, making it easy to track and manage accounts at a glance.


multi-apps-1


Switching to the graph view gives you a better representation of how your account tree looks

multi-apps-1

Creating sub-accounts

To create sub-accounts, users with the necessary permissions can go to the All Accounts section and click Create New Account. They just need to specify an account name and choose a parent account.

If a an account has sub-account management enabled and the user holds the fe.account-hierarchy.write.sub-account-management permission, they can enable or disable sub-account management for child accounts. When enabled, the child account can access the All Accounts page.

multi-apps-1

Managing individual sub-accounts

To access specific sub-account details, click on the account name in either the table or graph view. There, you'll see a summary, including the account name, its hierarchy, user count, and sub-account total.


multi-apps-1

To delete a sub-account, navigate to the sub-accounts section in your master account and choose the sub-account you want to remove. Then, proceed to delete the sub-account, which will promptly remove it from the hierarchy. Please note that sub-accounts can only be deleted if they have no associated children.

Explicitly inviting users to accounts

You can invite users directly to accounts by clicking the Invite Users button. When you do so, they will receive an activation or an invitation by email.

multi-apps-1

Granting access to sub-accounts and future sub-accounts

Grant user access to an entire hierarchy branch by assigning it at the parent account level. This grants the user full access to all current and future sub-accounts within that branch, allowing them to switch between accounts if the functionality is enabled. The role assigned at the parent account automatically applies to all sub-accounts in the branch.

Users can be granted automatic access to sub-accounts and future sub-accounts through both the Admin portal and the Backoffice.

Sub-account access can be configured during the invitation process or modified later for individual users, offering flexibility and precise control over user access across the hierarchy.

Admin portal:

  1. Upon user creation - navigate to the "All Accounts" tab, select a specific account, click "Invite user" and toggle the access option before inviting.

multi-apps-1

  1. Update an exiting user - navigate to the "All Accounts" tab, select a specific account, and toggle on "Sub-account Access" in the user's list to enable access to all sub-accounts.

multi-apps-1

Backoffice:

  1. Upon user creation - navigate to the accounts page in a specific environment, choose a specific account, click "Create user" button. Set the user information and toggle on the "Sub account access".

multi-apps-1

The sub-account access toggle will appear only if the current account is defined as a parent account.


  1. Update an existing user - navigate to the accounts page in a specific environment, choose a specific account,for a specific user via the 3 dots icon choose "enable access to sub-accounts", this action can be reversed.

multi-apps-1

Switch to sub-accounts

  • When users are granted access to sub-accounts, the accounts where they are allowed, will not appear on the user's access token (JWT) or the users state. i.e, to implement an account swither in this case, will require calculating behind the scenes which accounts the user should have access to, via APIs.
  • Sub account access will be visible only for users belonging to accounts with a hierarchy-based account structure.

Sub-account access settings

To allow users set default sub-accounts access, make sure they have fe.account-hierarchy.write.subAccountAccess permission. Then, under All Accounts tab in your application's self-service under the three dots at the top right corner of the account page, find the settings. End users can select the default state for new users that will be invited to the application.


multi-apps-1


The Default off setting prevents users from accessing sub-accounts upon invitation. You can change this default on demand.

Default on gives users sub-account access by default. You can change this default on demand.

Always on affects all account users (current and future) and cannot be revoked. If you change it later to Default on or Default off, the users who were invited to the account previously will still have access. The settings will only affect future users.


Existing and Future Users

When you invite users to accounts where Always on is enabled, both existing and future users of the account will get sub-account access. For Default on & Default off accounts, the settings will become effective for future users only.