Modeling Hierarchies | FusionAuth Docs

/ Docs

Light<br>Dark<br>System

Log In

Get a demo

Open main menu

Modeling Hierarchies

This guide discusses ways of modeling hierarchical organizations and entities, with users and permissions, and provides an example script you can use in your own website. Entities are not available in the free version of FusionAuth.

This feature is only available in paid plans. To learn more, see our pricing page.

Understand FusionAuth Types And Their Relationships#

Before continuing, please read the review of FusionAuth types and how they relate. You need to understand these types well to adjust the hierarchical system design in this guide to suit your situation.

To avoid confusion with FusionAuth applications in this guide, the service you provide your users will be called your "website", as opposed to an application, app, or service.

An Example Company Hierarchy With Permissions#

None of the FusionAuth types are hierarchical. In other words, no types can be nested in any other types. Groups can't be members of groups, applications can't contain other applications, and entities don't have sub-entities.

This is a problem when trying to model organizations that are hierarchical, especially when trying to decide when a user who has permissions to one level of the hierarchy should have permissions to an entity somewhere in the hierarchy.

Let's take an example. Assume that you want to use FusionAuth to authorize users in your corporation, Change Corp, to have access to certain documents. Your corporation has two sub-companies: Change Bank and Change Insurance. Each company has many departments, like marketing, sales, finance, operations, and management. Documents belong to a single department in an organization. Companies, departments, and documents have read and write permissions.

Permissions propagate downwards. So an employee with write permissions to the marketing department in Change Insurance will have write permissions to all its documents. And an employee with read permissions to Change Corp has read permissions to every document in every department of both sub-companies. But you might have an auditor who you add as a user in FusionAuth that has only read access to a specific document in a specific department. This will not give her permissions to any other documents anywhere higher in the organizational hierarchy.

Below is a diagram of the company structure to model.

graph BT<br>n1[Change Corp]<br>n2(Change Bank)<br>n3(Change Insurance)

n4[/Operations/]<br>n5[/Finance/]<br>n6[/HR/]<br>n7[/Operations/]<br>n8[/Finance/]<br>n9[/HR/]

n10((Alice))<br>n11((Bob))<br>n12@{ shape: doc, label: "Passwords doc" }<br>n13@{ shape: doc, label: "Financial statements" }<br>n14@{ shape: doc, label: "HR manual" }

n2 --o n1<br>n3 --o n1<br>n4 --o n2<br>n5 --o n2<br>n6 --o n2<br>n7 --o n3<br>n8 --o n3<br>n9 --o n3

n10 --o n4<br>n11 --o n5<br>n12 --o n4<br>n13 --o n5<br>n14 --o n9

Company structure

note<br>You can probably see some challenges already:

How do you handle documents that everyone in the corporation needs to read, such as a corporate HR manual, which is managed by the HR department of the top-level corporation? Because permissions don't propagate upwards, you have to individually give read permissions to everyone, instead of relying on the hierarchy to do it automatically.

What happens when permissions conflict? The operations department might have a passwords document that should have read access only by members of that department, but anyone with read access to the sub-company will have access to the passwords.

There are solutions to these problems, such as including "Deny access" permissions and a "Common" department for shared documents, and you need to pick what works for your organization. These challenges won't be discussed in this guide, as you can use the techniques shown here to implement your own solution.

How To Model Hierarchy In FusionAuth With Entities And Grants#

The best way to model a hierarchy in FusionAuth is with Entities.

For the example above, you should create entity types Company and Department with permissions Read, Write, and IsMember. Read and write are used to show permissions, but IsMember is used to show hierarchy.

Then create an entity called Change Bank of type Company and entity of Department called Operations. Create an entity grant for Operations to Change Bank with IsMember set to true to show that this Operations entity belongs to the Change Bank entity. Note that it will not be possible to tell departments called Operations in different companies apart by their name alone. You will need to examine each department's entity grant to see which company it belongs to.

Finally, you'll create an entity grant for user Alice to entity Change Bank with no permissions, and an entity grant for Alice to Operations with permissions Read and Write. Below is a diagram of this example, which is similar to the earlier types diagram, but includes a department hierarchy now. Permissions are shown in separate blocks...