Multi-Tenancy
Describes how Form.io works with Multi-Tenant deployments
Introduction
The Form.io platform easily handles complex multi-tenanted SaaS/PaaS application configurations. Form.io Multi-Tenancy enables each tenant to have an isolated sandbox of Forms, Resources, Data, Roles and Permissions, and Project Settings which all can be configured within an independent domain, using the user-friendly UI inside the Form.io Developer Portal Application. Paired with our Form Manager Application, this also enables SaaS and PaaS companies the opportunity to offer the Form.io platform as a white-labeled, multi-tenanted form building engine that can scale and serve an unlimited amount of their customers, all from a centralized deployment of the Form.io platform. The following diagram illustrates this concept.
In order to utilize the Form.io Multi-Tenant capabilities, you will need to first enable this feature within your License.
Contact sales@form.io for more info about enabling Multi-Tenancy in your environment
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
Click the Tenant button in the left-hand navigation bar to access the Tenant Manager UI.
The Tenant Manager lists all of your current tenants and associated settings that can be configured for each Tenant. Use this UI to manage your organizational tenants that reside within your project.
Tenant Creation
To create a new Tenant within your project, click the + Create Tenant.
The first thing to do is determine where the Tenant will be created from. Click the Copy From dropdown and select which Stage within your project the Tenant will be copied from. All Forms and Resources from the copied stage will be cloned into the tenant. This allows you to use one of your Stages as a Template for every new tenant you create. This can assist with the customer onboarding process allowing new customers to quickly receive their API endpoint and providing all of the necessary forms and resources.
Give the Tenant a name and click Submit to finalize the Tenant creation.
If an Admin user is needed to manage the Tenant, check the Create an Admin user checkbox and provide credentials before submitting the tenant.
Tenant Navigation
To navigate between Tenants, click the Open button to the right of the Tenant name. Once opened the Developer Portal will switch to the context of that tenant. Use the Portal exactly how you would any other project or stage by creating and managing forms, resources, data, and configurations for the given Tenant.
Once inside the Tenant context, notice the API endpoint has been updated for that specific Tenant. Use this endpoint within your application to control which tenant the forms and resources are communicating to.
Tenant Configurations
Let's suppose you are developing an application that accepts a CSS file or logo parameter and you would like these settings preconfigured each time a new Tenant is created. Tenant Configuration allows you to create a Configuration Form inside your project to include configuration settings for each Tenant that you create. These settings relate directly to the Public Configuration settings detailed here.
Create your Configuration Form the same way you would create any other form using the form builder. Add a text field to the form that will represent your configuration and save the form (remember to remove the submit button). In the following example, I've added a Logo and CSS field to represent my global configuration for my Tenants.
Once you have your form, navigate to the Tenant Manager and click the Settings tab to map the Configuration Form and Save Settings.
Next, create a new Tenant and input the configuration Values you would like this Tenant to carry. Once you create the Tenant, the values of this form will then be used to populate the public configuration of that tenant which can then be utilized by the connected application.
Within the Tenant, navigate to the Public Configurations to review the settings that were mapped by the Configuration Form.
Tenant Usage
Now that we have some tenants set up, 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 and integrations such as Email Transports, OAuth Providers, SAML Authentication, etc. Each Tenant's settings can be configured like you would configure any other project settings.
Ensure you have opened the Tenant and inside the Tenant context before making any configuration changes.
Tenant Authentication
Just like every tenant controls their own settings, each tenant also requires their own authenticated 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. Solution this by checking the Create an admin user checkbox when creating a new Tenant. Input the admin credentials and create the Tenant which will create an Admin account inside the Admin Resource for the created Tenant.
Tenant Setup Examples
The following examples are common use cases for setting up and utilizing Tenants within the Form.io platform.
Multi-Tenanted Child Project
In this example, we are going to create two Tenants inside our parent project, Tenant A and Tenant B. Each Tenant will carry its own public configurations provided by the Tenant Configuration Form. Each Tenant will have two independent Stages for Form Building and Production use with each stage independently connected to their own Remote Environment.
Setup a Configuration Form
Within your parent project, create your Tenant Configuration Form.
Create Tenants
Navigate to the Tenant Manager and create two Tenants, Tenant A and Tenant B. Input Tenant Configuration values using the Configuration Form created in the previous step.
Create Stages
Within each Tenant, create a Form Building and Production Stage. The Form Building stage is where developers/form designers will create their forms. Once the forms have been tested and approved, the Form Building stage will then be Deployed to the Production stage to be used in the live application.
Connect Stages to Remote Environment
With stages in place, connect each stage to its own Remote Environment. This ensures each stage is represented by its own database environment, separating the production database from the Form Building and QA database.
Multi-Tenanted Form Manager
This example will showcase how to set up tenants connected to the Form Manager application. The setup will be similar to the previous example, however, we will be focused on connecting independent tenants to their own custom Form Manager. This enables the ability to offer a white-labeled, customized, branded Form Building interface on a per-tenant basis. This is managed all from within the Form.io Developer Portal.
Setup a Configuration Form
Within your parent project, create your Tenant Configuration Form. The configuration fields within the form will dictate what setting variables will be applied to each Tenant's Form Manager application. For this example, we will use the Logo and CSS configuration variables:
Title, Logo, CSS
Create Tenants
Navigate to the Tenant Manager and create two Tenants, Tenant A and Tenant B. Apply unique Tenant Configurations for each Tenant using the Configuration Form created in the previous step.
Tenant A:
Title:
Logo:
CSS:
Tenant B:
Title:
Logo:
CSS:
Create Users
Since each independent Tenant has its own endpoint and database, Create Users for each tenant to authenticate into the connected Form Manager application.
Form Manager Application
Now that we have our user accounts created, launch the Form Manager Application inside each tenant and login using the account credentials created in the previous step. Take note of the unique configuration settings applied to each Tenant displayed inside the Form Manager Application.
Last updated
