Entity Management

This feature is only available in paid editions of FusionAuth. Please visit our pricing page to learn more about paid editions.

Overview

There are many use cases where it is helpful to model entities in addition to users. Examples might include devices, cars, computers, customers, companies, etc.

Enter Entities. Entities allow you to model everything right from FusionAuth!

Features
Common Applications
Entity Types
Entity
SCIM Configuration
Limitations
More Information

Features

Scalability

FusionAuth Entity Management supports large volumes of Entities right out of the box.
This is especially helpful for Internet of Things (IoT) devices; FusionAuth scales right alongside them.

Typecasting

Entities can have a type.
For example, an Entity could be a type of lock, car, company, corporate division, computer, or API
Entity Types can define permissions.
You are limited only by your business need and imagination!

Permissions Aware

Permissions can be assigned to each Entity Type.
Entities can be granted permissions on other entities (In OAuth terms, entities can initiate a Client Credentials Grant to obtain access to other entities).
Users can have permissions to access Entities.

Common Applications

Corporate relationship modeling
Per use device permissions
Internet IoT

Below is an example diagram using the client credentials grant, and an email Entity Type.

Can’t I Just Use a Group?

In some cases, Groups work as a model for such ideas like customers. However, the flexibility of Groups is limited by their lack of typecasting (very much needed as use cases evolve). Additionally, Groups do not have a hierarchical model or permissions functionality built in.

Entity Types

This is the Entity Types homepage. Here you can:

Create a new Entity Type

Edit a previously created Entity Type

Manage Permissions on Entity Type

View the previously created Entity Type

Remove the previously created Entity Type

Add Entity Type Form Fields

Creating a new Entity Type is straightforward.

Just complete the following fields:

Id Optional: An optional UUID. When this value is omitted, a unique Id will be generated automatically.
JSON Web Token Settings Optional: If you need custom JWT signing algorithms. If unchecked, any tokens generated for this entity will use the Entity’s tenant jwt signing settings.
Name Required: The name of the Entity Type. This value is for display purposes only and can be changed at any time.

Manage Permissions Form Fields

Here you can add/manage custom permissions.
Below is an example if no permissions are set previously; the UI is similar if simply updating existing permissions.

Name Required: The name of the permission
Default Optional: If this permission should be assigned once the Entity Type is created (by default). More than one default can be set.
Description Optional: Please write a helpful description of the permissions' purpose.

Entity

This is the Entity homepage. Here you can:

Create a new Entity

Edit a previously created Entity

View the previously created Entity

Remove the previously created Entity

Add Entity Form Fields

Creating a new Entity is straightforward

Just complete the following fields:

Id Optional: An optional UUID. When this value is omitted, a unique Id will be generated automatically.
Name Required: The name of the Entity. This value is for display purposes only and can be changed at any time.
Tenant Required: Assign the new Entity to a Tenant
Client Id Optional: When this value is omitted a unique Client Id will be generated automatically.
Client secret Optional: When this value is omitted a unique Client secret will be generated automatically.
Entity Type Required: When creating this Entity, you can assign it to a previously created Entity Type

SCIM Configuration

This functionality has been available since 1.36.0

When configuring FusionAuth to accept SCIM requests, you must create a SCIM server Entity and a SCIM client Entity. These entities will be used by the Client Credentials grant which will provide the access token which is used to authenticate calls to the SCIM endpoints. These entities must be of the Entity Type configured in the Tenant SCIM configuration. They also must have the SCIM permissions granted to successfully call SCIM API endpoints requiring authentication.

The necessary Entity Types can be created by navigating to Entity Management > Entity Types and selecting the clicking the drop down Add button in the top right of the page. In most cases you will find these two entity types have been created for you by FusionAuth.

The default entity types are named [FusionAuth Default] SCIM client and [FusionAuth Default] SCIM server. Below is a screenshot of adding a new Entity Type for the SCIM Server, but if you wish to use the default Entity Type, you do not need to create an additional Entity Type.

SCIM server permissions

Below is a list of available permissions that can be included in your SCIM server entity type. Each controls access to a single API endpoint. You can choose to create as few or as many of these as you require. The names must match exactly.

Name

Access to API

scim:user:create

scim:user:read

scim:user:update

scim:user:delete

scim:enterprise:user:create

Create an Enterprise User

scim:enterprise:user:read

Retrieve an Enterprise User

scim:enterprise:user:update

Update an Enterprise User

scim:enterprise:user:delete

Delete an Enterprise User

scim:group:create

scim:group:read

scim:group:update

scim:group:delete

Limitations

It is not currently possible to utilize an OAuth2 grant to retrieve user permissions to an entity. Please review GitHub Issue #1295 and vote if you would like to see this capability in FusionAuth.

It is also not possible to rename or otherwise customize scopes used with Entity Management. Please review GitHub Issue #1481 and vote if you would like to see this capability in FusionAuth.