Describes how Form.io works with Multi-Tenant deployments


The Form.io platform is built to work with deployments requirement a multitude of separate tenants to build and manage their own forms. This feature enables each tenant to have isolated sandboxes where Forms, Resources, Roles and Permissions, and project settings can be configured within an independent domain within your platform. This enables other SAAS companies as well as PAAS companies to offer the Form.io platform as a white-labeled form engine that can scale and serve many different customers within a single deployment. The following diagram illustrates this concept.
In order to utilize the Form.io Multi-Tenant capabilities, you will need to first enable this from within your License. Please reach out to Form.io Sales to inquire about purchasing a multi-tenant license to support your independent customers.

About Tenants

Tenants are implemented within the Form.io platform as independent sub-projects where each Tenant receives their own Project endpoint. These tenant projects can be thought of as "sub-projects" where they have full project features, but have certain limitations that restrict how they can be used. The limitations imposed on the tenants within a project are CORS related where each sub-project must contain the same CORS limitations added to the parent project. This limitation makes it so that each tenant MUST be utilized from an application that is on the same domain as other tenants. This ensures that each tenant is not utilized as separate application projects, but rather as tenants within a single application deployment.

Tenant Manager

Once the Tenants feature has been enabled within your license, you will see the Tenants icon show up in your feature bar on the left hand side of your project page. Once you click on this icon, the Tenant Manager application will appear as follows.
This application is used to manage all of the tenants within your organization that reside within your project. Within the Tenant Manager is a list of all of your current tenants as well as the Settings that can be used to apply to each tenant.

Tenant Creation

The first thing you will do is create a new tenant. This can be done by clicking on the Create Tenant button. Once you do this, you can then provide a name for this Tenant and then press the Submit button. Once this is done, the tenant will now show up in the Tenant list where it can easily be navigated to.
One important thing to mention is that every tenant created is a "clone" of the parent project. Because of this all of the Forms and Resources of the tenant project will also be cloned into the tenant project. This allows you to use the primary project as a Template project that is then used as the template to provide the default project structure for every new tenant created. This will assist with the customer onboarding process where new customers can quickly receive their API endpoint that has all of the default forms and resources automatically configured.

Tenant Navigation

Within the Tenant list, you will have the ability to navigate to each tenant where the Developer portal will change contexts to that specific tenant. The way that this works is by clicking on the Open link next to each tenant, the Developer portal will switch to be within the context of that tenant. You can then use the portal like you would connected to any other stage to manage the forms, resources, data, and configurations for that specific tenant.
You can now use the API endpoint for that Tenant within your application as the mechanism to control which tenant the forms and resources are communicating to.

Tenant Configurations

Within the Settings tab is where you can set the Configuration Form for each tenant. The way that this works is as a way to configure the Public Configuration setting for every tenant that is created. For example, let's suppose that you are building an application that accepts a "logo" parameter for each of the tenants that are created. You could create your configuration form by creating the following form within your project (make sure to remove the default Submit button).
Once this form is created, it can now be set within the Tenant configuration settings like so.
Once this is done, now every Tenant that is created will show this form for the Public Configuration of that tenant. Once you create a new Tenant, the values of this form will then be used to populate the public configuration for that tenant which can then be used within the application to make application changes per-tenant.
Once this tenant is created, you will then see the following within the Public configuration for that Tenant.

Tenant Usage

Now that we have some tenants setup, we are now ready to build our application to use them.

Tenant Settings

Since every Tenant is technically a separate Project, this means that we must use the Settings for each tenant as separate configuration efforts. This also allows each of your tenants to have their own settings for things such as Email Providers, OAuth Providers, SAML authentication, etc. Each Tenant's settings can be configured like you would configure any other project settings, but you must ensure that you are in "context" of that tenant before making any configuration changes.

Tenant Authentication

Just like every tenant must control their own settings, you must also configure each tenant to authenticate their own users, including Administrators for that tenant. Since the template of the parent is configured for every new tenant, this means that users added to the primary project will not create users within each tenant. Because of this, you will need to re-add new user accounts within each tenant as the "default" users as they are being onboarded.