Create a new Multi-Tenant Application

Dec 12, 2025
3 minutes to read

Use XAF Application Builder to Create a New Application

In Template Kit, select the Multi-Tenant / SaaS-ready Application option and proceed to create project.

Note that not all application configurations support multi-tenancy. See Limitations for more information.

Tip

You can find the example of a multi-tenant application in our Outlook Inspired Demo.

Create and Initialize the Host Database

Follow the steps below to create and initialize the Host Database.

If required, change the ConnectionString setting in the application configuration file (appsettings.json in Blazor and App.config in WinForms).

Run the application in Debug mode and log in as Admin with a blank password. The framework executes the following tasks:

Creates the Host Database.
Creates the Super Administrator user with the login "Admin" and a blank password.
Switches the application to Host UI mode.

XAF Template Kit generates Module Updater code that creates an Admin user with a blank password. For security reasons, this user is not available if the application is compiled in Release configuration.

After you log in to the Host UI for the first time, we recommend that you change the Super Administrator’s password. You can also create additional Super Administrator accounts. These accounts must be assigned the Administrators role.

Create and Initialize Tenants

Follow the steps below to create a new tenant (named "company1.com" in this example).

In the Host UI, switch to the Tenants List View and add a new Tenant record. Specify the tenant name and a connection string for a new Tenant Database.

Log out from the Host UI and log in as the new tenant’s administrator ("[email protected]") with a blank password. The framework executes the following tasks:

Creates a database for tenant company1.com.
In this database, creates the following two users: "[email protected]" with the Administrators role and "[email protected]" with the Users role.

Take the following additional considerations into account:

Ensure that none of the tenants share their databases with other tenants. A Tenant Database must also never be the same as the Host Database.
An application does not immediately create a Tenant Database when the tenant is created. Instead, the database is created when a user logs in to this tenant for the first time.
A tenant name must be unique.
XAF Template Kit generates Module Updater code that creates the Admin@tenant_name and Usern@tenant_name users with blank passwords. For security reasons, these users are not available if the application is compiled in Release configuration.
After the first login to the Tenant User Interface, it is recommended that you change passwords for all automatically created users.

Create Tenant Users and Manage Access Permissions

Tenant users and their access permissions are managed in the Tennant User Interface independently from other tenants and from the Host User Interface. Each tenant has its own independent list of users, roles, and security permissions.

To create a new Tenant User in a company1.com tenant, you need to:

Log in with a tenant administrator account ([email protected]).
Create a user with the standard user editing interface (the same as in a single-tenant XAF application).

When you create tenant users, we recommend that you pay special attention to how you specify user logins. For example, if you use TenantByEmailResolver or a TenantByUserNameResolver descendant to determine user tenants, a user’s login must be specified in accordance with the exact name and format of their tenant. Otherwise, the system will not be able to identify the tenant on the user’s login attempt, which will make the user unable to log in.