Entity Management

This feature is only available in paid plans. Please visit our pricing page to learn more.

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! Entities allow you to model relationships and enable machine-to-machine authentication using the Client Credentials grant.

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:

Entity Type Form Fields

Permissions

Add and manage custom permissions.

JWT

Controls the JWT settings used for this entity type.

Entity

This is the Entity homepage. Here you can:

Entity Form Fields

Creating a new Entity is straightforward

Just complete the following fields:

SCIM Configuration

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.

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.

More Information

• An example client credentials grant using Entities.
• The Entity Management APIs.
• A guide to using Entities to model organizations.