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! 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, orAPI -
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 |
Entity Type Form 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 Type. This value is for display purposes only and can be changed at any time.
Permissions
Add and manage custom 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.
JWT
Controls the JWT settings used for this entity type.
- Enabled Optional
-
When enabled, you can specify JWT settings for this entity type. If disabled, settings for the entity’s tenant will be used.
- JWT Duration Required
-
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 Optional
-
The key used to sign the JWT.
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 |
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 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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.