Overview

This module allows you to setup your app for multi tenant usage. You can use this module to control the tenants and the users within the tenants. For those users this replaces the default Administration module, for users that transcend the tenant level you still need the Administration module.

Documentation

Introduction

This module is your solution to control multiple tenants and their users in a single application.

Typical Use Cases

Use this module for apps that need to support multiple tenants.

Features & Limitations

• Configure grantable roles in runtime
• Manage tenants and their users
• Manage your own account as a tenant user
• Should be compatible with SAML 2.0

Prerequisites

• Mendix Desktop Modeler version 7.5.0 or higher for major version 7 (does not work automatically with Studio Pro versions 8 and above)

Installation

Download the module into your app.

Configuration

• Ensure you do not set the grantable roles via your app security for user roles that do not transcend the tenant level.
• Add the ASU_UserRoles microflow to the after-startup event of your app.
• Use the ProjectUserRoleManagement snippet in one of your own pages to manage the grantable user roles.
• Use the Tenants snippet in one of your own pages to manage the tenants.
• Use the TenantUsers snippet in one of your pages to manage the tenant users.
• Use the ManageMyAccount microflow to let users manage their own account.

How to Set Up a Multi-Tenant App

Are you thinking about making your app multi-tenant but are not sure about how to start or what challenges you might come across? It might not seem that complex to build a multi-tenant app, but there are several best practices that will ensure you are building a secure and well-performing app for your customer.

Please note this how-to is not supported by Mendix, but it can provide help when you want to set up a multi-tenant app.

App Security

In a multi-tenant app, you want to differentiate between user roles that transcend the multi-tenant part of the app (for example, Functional Administrator and Technical Administrator) and those that do not. This is due to the way the Mendix Platform combines the settings of the user management in the Project Security and access rules on entities that are a specialization of the System.User entity.

The user roles allocated to users that act as a tenant user should not have a configured user management. This is to prevent any user with that user role from seeing users from other tenants. A tenant admin or another tenant-related type of user role must be configured as shown here, which is the desired way of setting user management for tenant-related user roles.

Use the Administration module functions to manage users that transcend the tenant level, and use this module to manage all users with tenant-related user roles.

When you select the (No user roles) option, this means that you can see all the users that do not have a user role linked to their account.

What you see above in the User management section is that none of the check boxes are set. This has the desired behavior of not seeing other tenant users, but it also has the undesired behavior of not being able to select a user role for your users. A solution for this is explained below.

Multi-Tenant Administration

This module can be used to handle your user management for a multi-tenant app and manage user roles, tenants and their users.

Let’s first have a look at the domain model of this module to understand its structure.

Domain Model

The domain model in the solution supports functions to manage user roles, tenants, and tenant users. There is a Tenant, which is the equivalent of an Organization.

The TenantUser is the entity that can sign in. Attributes are used that look like the attributes of the System.User entity. The big difference is that you are now in control! As you can also see, the TenantUser is allowed to inherit from System.User and not from Administration.Account. This is done to prevent a negative impact on the performance of this entity by removing unnecessary levels of depth in the inheritance structure.

In the domain model, one delete prevention rule on the TenantUser_Tenant association is also included. This is added to prevent the accidental removal of a tenant.

The ProjectUserRole entity is used for duplication of the System.Userrole instances.

The ProjectUserRole_UserRole is 1-* association is due to the deprecation notice that states, "Cross-module association to the System module must have the Owner property set to Default."

To make use of the same change-password functionality, the same type of functions are included as in the Administration module.

User Role Management

The second step is to rebuild the user management functionality for user roles as you normally would via the Security. To make this possible, the functions below have been added to the module.

With an after-startup event, the ProjectUserRole entities are synchronized with the System.UserRole entities. This way you can use the ProjectUserRole entities to select a user role for your tenant users. The Administrator user role is not synchronized, because this will never be assigned to a tenant user.

An Administrator can view all the synchronized user roles and set the grantable roles for those user roles during runtime. Without setting the grantable roles, no tenant admin will be able to assign a user role to a user.

Tenant Management

The next step is to manage the tenants. This is a function that is offered to the administrator role and consists out of the standard CRUD access.

Tenant User Management

Now that you have user roles and tenants, you can create users for the tenants. This feature is available for Administrators and Tenant Administrators. This way, the Administrator can create at least one user for each tenant, and this user can create more users for their own tenant. By default, the email address is used as a username. This is done to overcome a duplicate username error due to a situation where different tenants would like to use the same username.

Other Challenges

Next to adjusting your project security and implementing this module, there are several other challenges you might come across.

Security

The way to start protecting the data of your app is to set access rules on the entities in your domain model. In a multi-tenant app, it is required to add an XPath constraint to your access rule. This constrains your data to your tenant. In this way, you prevent tenants from seeing information of other tenants.

Performance

When you are building an app, you can find yourself creating complex domain model structures. When an entity is referenced via numerous entities to your Tenant entity, you can imagine that your XPath will become quite large. This will result in large SQL queries that will cost performance.

A solution for this is to add an additional reference directly between your entity and the Tenant entity. This way, you can limit your XPath to this path and it will boost your performance.