Entity Management

FusionAuth Reactor logo

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.

Client Credentials Grant Diagram

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

Home Screen 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

Entity Type Form Fields

Create an Entity Type
Id

An optional UUID. When this value is omitted, a unique Id will be generated automatically.

Namerequired

The name of the Entity Type. This value is for display purposes only and can be changed at any time.

Permissions

Add and manage custom permissions.

Entity Homepage
Namerequired

The name of the permission

Default

If this permission should be assigned once the Entity Type is created (by default). More than one default can be set.

Description

Please write a helpful description of the permissions’ purpose.

JWT

Controls the JWT settings used for this entity type.

Create an Entity Type - JWT tab
Enabled

When enabled, you can specify JWT settings for this entity type. If disabled, settings for the entity’s tenant will be used.

JWT Durationrequired

The length of time specified in seconds that the issued token is valid. This value must be greater than 0.

When JWT customization is enabled, this is required.

Access token signing key

The key used to sign the JWT.

Entity

Entity Homepage

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

Entity Form Fields

Create an Entity

Creating a new Entity is straightforward

Just complete the following fields:

Id

An optional UUID. When this value is omitted, a unique Id will be generated automatically.

Namerequired

The name of the Entity. This value is for display purposes only and can be changed at any time.

Tenantrequired

Assign the new Entity to a Tenant

Client Id

When this value is omitted a unique Client Id will be generated automatically.

Client secret

When this value is omitted a unique Client secret will be generated automatically.

Entity Typerequired

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.

Home Screen SCIM Entity Types

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.

NameAccess to API
scim:enterprise:user:createCreate an Enterprise User
scim:enterprise:user:readRetrieve an Enterprise User
scim:enterprise:user:updateUpdate an Enterprise User
scim:enterprise:user:deleteDelete an Enterprise User
scim:group:createCreate a Group
scim:group:readRetrieve a Group
scim:group:updateUpdate a Group
scim:group:deleteDelete a Group
scim:resource-types:readRetrieve Resource Types
scim:schemas:readRetrieve Schemas
scim:service-provider-config:readRetrieve Service Provider Configuration
scim:user:createCreate a User
scim:user:readRetrieve a User
scim:user:updateUpdate a User
scim:user:deleteDelete a User

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