Sign up for a new tenant, with versioning

Version 3.3.0 of the AuthP library provides a service that allows an external user to sign up for a new tenant. This makes it easy for anyone sign up to your application - this type of approach is called self-service provisioning. The service also contains an optional feature called versioning where you can provide tenants with different features (and prices). This allows an new user to:

• Create a new tenant for their company / organisation
  • If your application uses versioning, the the new user can choose (and pay) for the version they suite them
• The new user is registered to your application and is linked to new tenant
  • And optionally the new user can designated as an tenant admin, which allows that user to manage the users within their tenant

The service supports all types of tenants (single-level, hierarchical, hybrid or sharding-only modes) and via the add New User adapter it can work with different ASP.NET Core authentication handlers.

Setup the “sign up / versioning” service

The "sign up / versioning" feature uses two services in the AuthPermissions.SupportCode namespace.

• The ISignInAndCreateTenant \ SignInAndCreateTenant, which implements the “sign up / versioning” service.
• The IAddNewUserManager service which the SignInAndCreateTenant relies on for adding a new user - see Add New User adapter for more on this service.
• And if you Sharding turned on, then you need to register your implementation of the IGetDatabaseForNewTenant interface - see IGetDatabaseForNewTenant service at the end of this document.

Any code in the AuthPermissions.SupportCode project has to be manually, and the code shown below is taken from Example 3 during the registering of the service to use in your ASP.NET Core application.

//Add the SupportCode services
services.AddTransient<IAddNewUserManager, IndividualUserAddUserManager<IdentityUser>>();
services.AddTransient<ISignInAndCreateTenant, SignInAndCreateTenant>();
//If Sharding is turned on then include the following registration
services.AddTransient<IGetDatabaseForNewTenant, YourVersionOfThisService>();

Note that the IAddNewUserManager service uses an implementation called IndividualUserAddUserManager<IdentityUser> which works with applications using the individual user accounts authenticate provider. Version 3.3.0 only contains two implementations of the IAddNewUserManager interface. They are:

• IndividualUserAddUserManager<TIdentity> which works with the individual user accounts authenticate provider.
• AzureAdUserManager which works with Azure AD authenticate provider (NOTE: won't work with Azure AD B2C with social logins).

More implementations may be added, or you can build your own by implementing the IAddNewUserManager interface.

Setting up the versions data (optional)

If you want to use the versioning feature you need to create a MultiTenantVersionData class containing the different features for each version. There are three parts to the versioning:

• TenantRolesForEachVersion that defines the Tenant Roles which will add extra features to the different versions.
• TenantAdminRoles which defines the Roles that the new user should have - this allows you to decide if the users gets admin Roles.
• HasOwnDbForEachVersion is required if Sharding is turned on. It allows you to define whether the tenant will have its own database (i.e. Sharding) or are in a database with other tenants.

Each of these properties are a Dictionary, where the string Key holds the name of the version. The code below comes from Example 7

public static readonly MultiTenantVersionData TenantSetupData = new()
{
    TenantRolesForEachVersion = new Dictionary<string, List<string>>()
    {
        { "Free", null },
        { "Pro", new List<string> { "Tenant Admin" } },
        { "Enterprise", new List<string> { "Tenant Admin", "Enterprise" } },
    },
    TenantAdminRoles = new Dictionary<string, List<string>>()
    {
        { "Free", new List<string> { "Invoice Reader", "Invoice Creator" } },
        { "Pro", new List<string> { "Invoice Reader", "Invoice Creator", "Tenant Admin" } },
        { "Enterprise", new List<string> { "Invoice Reader", "Invoice Creator", "Tenant Admin" } }
    },
    HasOwnDbForEachVersion = new Dictionary<string, bool?>()
    {
        { "Free", true },
        { "Pro", true },
        { "Enterprise", true }
    }
};

Create the tenant and register the user

You need an action / page which can be accessed by a user who isn't logged in to sign up for a new tenant - see Example 3 with the "Sign up now!" link on the Home navbar. The data your will need are:

• The email of the new user (optionally their UserName too)
• The name they want for the tenant
• Depending on which authentication provider you selected (see Add New User adapter) you might need the password the new user wants to use.

The SignInAndCreateTenant service has two methods, one for no versioning and one that uses versioning. The two subsections describe how to use each approach.

Creating tenant - no versioning

In this case you use the SignUpNewTenantAsync(AddNewUserDto newUser, AddNewTenantDto tenantData) method which takes in:

• newUser which contains the new user's information, e.g. email, username, password, plus the Roles that the new user should have.
• tenantData which should contain the TenantName for the new tenant. If Sharding is turned on you must also provide set the HasOwnDb property to true or false and the Region property can be used if you have geographically spread out database servers and is used by IGetDatabaseForNewTenant service to pick the correct database server location.

Creating tenant - with versioning

In this case you use the SignUpNewTenantWithVersionAsync(AddNewUserDto newUser, AddNewTenantDto tenantData, MultiTenantVersionData versionData) method which takes in:

• newUser which contains the new user's information, e.g. email, username, password, plus the Roles that the new user should have.
• tenantData which should contain the TenantName for the new tenant and the Version property should contain a valid version name. If Sharding is turned on and your database servers are geographically spread out, then you can set the Region property which will be used by IGetDatabaseForNewTenant service to pick the correct database server location.
• versionData which defines the configuration of the tenant (see Example3CreateTenantVersions example shown earlier in this document).

Register the user

Once the new tenant is created the new user is registered as a valid user for the new tenant. Then the new user is logged in.

NOTE: If the registering of the new user fails the new tenant is deleted so that the user can try again and the tenant name is still available to them.

IGetDatabaseForNewTenant service

This service has one method called FindBestDatabaseInfoNameAsync which is used in the Sign up for a new tenant, with versioning feature when the multi-tenant application is using sharding and its job is to return the name of the DatabaseInformation which defines the database the tenant should created in. This is a complex calculation because there many options:

• Does the tenant need a dedicated database, or does it go into a database that has multiple tenants in it? (see this diagram)
• Are you using multiple database servers spread of geographically? In this case you want to pick the nearest server / database.

There is no one solution to this as it depends on your application, so the AuthP library defines the IGetDatabaseForNewTenant interface and you need to implement and then manually register your service, e.g.

//manually add services from the AuthPermissions.SupportCode project
builder.Services.AddTransient<IGetDatabaseForNewTenant, YourGetDatabaseCode>();

Example of the IGetDatabaseForNewTenant service

As explained, there isn't a standard solution so you need to implement your own, but help you there is some demo code with examples of what you might do.

Hybrid approach, where the admin user creates the sharding entries

The DemoGetDatabaseForNewTenant class provides demo code supports the hybrid approach (e.g. both shared and shard-only tenants) but doesn't have multiple database servers spread of geographically. Its goals are:

• Pack all the shared tenants into a database, but not more than 50 tenants.
• Shard-only tenants take any empty database.
• If no databases are available it returns an error (you could create a new database and also update the sharding entries, but that depends on your production system)

NOTE: This demo isn't used in any of the Examples

Shard-only approach, where the code can create sharding entries

The DemoShardOnlyGetDatabaseForNewTenant creates a new sharding entry an tenant when a user uses the "Sign up" feature. This service relies on the changes added to the code in AuthP version 6, which allows the sharding entry to be written and read back in the same HTTP request.

The DemoShardOnlyGetDatabaseForNewTenant is used in Example7 applciation in the AuthP repo.

Additional resources

• Add New User adapter