About Tenant Nesting
Tenant nesting is a version of multi-tenancy that allows you to sub-divide your application into multiple tiers of access.
A tenant is a single sub-division of your application, such as a customer’s organization. Tenant nesting means that you can also sub-divide each tenant into child tenants.
By using tenant nesting, you can model access to your service and the accounts within your service at a fine-grained level, which improves security, compliance, and end user experience.
A user can have roles in zero, one, or many different tenants.
Tenants come in 3 flavors:
Tenant type
Description
With nested multi-tenancy, you can create organizations and sub-organizations within your application. Userfront has the ability to further nest tenants as many layers deep as your needs require.
Tenant Nesting Requirements
To use roles and tenants on Userfront, create and manage your roles, tenants, and users from the dashboard or API.
Each end user also has an authorization object that contains the tenants and roles that they can access.
This authorization object is included in their JWT access token by default, and can also be obtained via the /self API endpoint.
{
"email": "bgates@example.com",
...
"authorization": {
"wbmxvmvn": {
"tenantId": "wbmxvmvn",
"name": "Organization A",
"roles": ["contributor","support"]
},
"qbjxdgxb": {
"tenantId": "qbjxdgxb",
"name": "Sub-org B1",
"roles": ["admin"]
}
}
}Cascading access
By default, when a user has a role in a parent tenant, the user will also have access at the same level for all descendant tenants of the parent. This is known as cascading access.
If desired, you can disable cascading access so that users only have access to the exact tenants for which they have roles, and not for any descendant tenants.
Machine-to-machine authorization
You can scope your Userfront tenants to model specific devices in your network, allowing for fine-grained machine-to-machine authentication and authorization.
For example, you could scope access via JWT access token or API key to all devices in a given category, or to a specific physical device. Similarly, you can receive and process requests scoped to a specific device, or to any level within your network hierarchy.
Each tenant on Userfront can have its own individual access levels, roles, API keys, and authentication settings.
Tenant Nesting Handling
Each tenant on Userfront has several objects related to tenant nesting: its parent, its children, and its descendantCount.
Term
Meaning
A typical API response from Userfront for a tenant will include the tenant’s parent, children, and descendantCount.
{
"name": "Organization A",
"tenantId": "wbmxvmvn",
...
"parent": {
"name": "Your application",
"tenantId": "abcd1234",
...
},
"children": {
"results": [
{
"name": "Child tenant",
"tenantId": "cdfg3456",
...
},
...
],
"totalCount": 5,
"totalPages": 1
},
"descendantCount": {
"children": 5,
"descendants": 7,
"basic": 4,
"multiuser": 2,
"enterprise": 1
}
}
