Multitenancy is a software architecture that allows a single instance of a software application to serve multiple customers, called tenants. Each tenant's data is isolated and remains invisible to other tenants for security reasons. This architecture is commonly used in Software as a Service (SaaS) applications, where multiple organizations or users share the same application infrastructure while keeping their data secure and separate.
Introduction to multitenancy
Multitenancy offers several advantages, including:
- Cost efficiency: shared infrastructure reduces the overall cost of hosting, infrastructure and maintenance.
- Simplified deployment: centralized updates simplify maintenance and support.
- Scalability: it allows easy scaling of resources for individual tenants based on their needs.
- Isolation and security: each tenant's data is isolated, ensuring security and privacy.
There are several approaches to separate data for each tenant in multi-tenant applications:
- Database-per-Tenant: each tenant has its own database. This model offers strong data isolation but may increase costs with many tenants.
- Schema-per-Tenant: a single database with separate schemas for each tenant. It provides a balance between isolation and resource sharing.
- Table-per-Tenant: a single database and schema, with tenant-specific tables. This model is efficient but may complicate data management.
- Discriminator column: a single database, schema, and tables, with a column indicating the tenant. This is the simplest but least isolated model.
Discriminator column is one of the most popular approaches to implementing multitenancy. It is cheap in terms of development, deployment and management compared to other options. With modern technologies like ASP.NET Core and EF Core, you can implement discriminator columns in your application without negatively affecting performance and security.
In this blog post I will show you how to implement multitenancy with discriminator column. Let's explore an application that needs to be multi-tenant.
Multitenant application example
Today we will implement multitenancy for the "Books" application that has the following entities:
- Books
- Authors
- Users
- Tenants
The Tenant entity holds information about each customer:
public DateTime CreatedAtUtc { get; set; }public class Tenant : IAuditableEntity
{
public required Guid Id { get; set; }
public required string Name { get; set; }
public DateTime? UpdatedAtUtc { get; set; }
}
Every Book, Author and User entities in our database belong to a specific tenant. You need to create a ITenantEntity interface that should be inherited by all entities that need to be multi-tenant:
public interface ITenantEntity
{
public Guid? TenantId { get; set; }
}
Let's explore, for example, User and Book entities:
public DateTime CreatedAtUtc { get; set; } public Guid? TenantId { get; set; } public class Book : IAuditableEntity, ITenantEntity public DateTime CreatedAtUtc { get; set; } public Guid? TenantId { get; set; }public class User : IAuditableEntity, ITenantEntity
{
public Guid Id { get; set; }
public required string Email { get; set; }
public DateTime? UpdatedAtUtc { get; set; }
}
{
public required Guid Id { get; set; }
public required string Title { get; set; }
public required int Year { get; set; }
public Guid AuthorId { get; set; }
public Author Author { get; set; } = null!;
public DateTime? UpdatedAtUtc { get; set; }
}
Every entity has a foreign key relationship with Tenant entity, for example, User:
builder.HasKey(x => x.Id); builder.Property(x => x.Id).ValueGeneratedOnAdd(); builder.HasOne<Tenant>()public class UserConfiguration : IEntityTypeConfiguration<User>
{
public void Configure(EntityTypeBuilder<User> builder)
{
builder.ToTable("users");
builder.HasIndex(x => x.Email);
builder.Property(x => x.Email).IsRequired();
builder.Property(x => x.CreatedAtUtc).IsRequired();
builder.Property(x => x.UpdatedAtUtc);
.WithMany()
.HasForeignKey(e => e.TenantId)
.IsRequired(false)
.OnDelete(DeleteBehavior.SetNull);
}
}
Depending on your application needs, you may have this foreign key or have a plain TenantId column without a reference.
How to implement multitenancy in EF Core
To implement multitenancy, we need to do the following:
- After a user logs in, we need to add a tenant identifier in the user claims.
- From every request from the frontend (or another application) whether we need to retrieve or modify data, we need to get the user tenant identifier from the user claims.
- Whenever a user requests data from the backend - we can use EF Core Global Query Filters to automatically filter only those records from the database that a user has access to.
- Whenever a user creates, updates or deletes data - we can automatically assign a "TenantId" column in the Change Tracker with a user tenant identifier.
By utilizing EF Core capabilities (Global Query Filters and Change Tracker) we no longer need to write custom filters in each query or provide a tenant id in every create, update or delete action. EF Core helps us to implement multitenancy once that will be applied to all entities that need to be multi-tenant.
This approach secures your code from the critical bugs where you may forget to add a check for a tenant in one of the queries and expose another customer's data.
Implementing multitenancy for read operations in EF Core
We can implement multitenancy in EF Core DbContext that will automatically be applied to all entities that inherit from ITenantEntity.
Let's define a TenantProvider that will retrieve user and tenant identifiers from the current HttpRequest:
public class TenantProvider : ITenantProvider public TenantProvider(IHttpContextAccessor accessor) Guid? userId = Guid.TryParse(userIdValue, out var guid) ? guid : null; _tenantInfo = new TenantInfo(userId, tenantId); public TenantInfo GetCurrentTenantInfo() => _tenantInfo;public interface ITenantProvider
{
TenantInfo GetCurrentTenantInfo();
}
{
private readonly TenantInfo _tenantInfo;
{
var userIdValue = accessor.HttpContext?.User.FindFirstValue("user-id");
var tenantIdValue = accessor.HttpContext?.User.FindFirstValue("tenant-id");
Guid? tenantId = Guid.TryParse(tenantIdValue, out guid) ? guid : null;
}
}
Here we retrieve the "user-id" and "tenant-id" from the ClaimsPrinciple.
You need to register the provider and IHttpContextAccessor in the DI:
builder.Services.AddHttpContextAccessor();
builder.Services.AddScoped<ITenantProvider, TenantProvider>();
We need to inject ITenantProvider into DbContext and create a public property for it:
public DbSet<Author> Authors { get; set; } = default!;public class ApplicationDbContext(DbContextOptions<ApplicationDbContext> options, ITenantProvider tenantProvider) : DbContext(options)
{
public ITenantProvider TenantProvider => tenantProvider;
public DbSet<Book> Books { get; set; } = default!;
public DbSet<User> Users { get; set; } = default!;
public DbSet<Tenant> Tenants { get; set; } = default!;
}
In the OnModelCreating method you can specify Global Query Filters for all our tenant entities:
modelBuilder.Entity<Author>() modelBuilder.Entity<Book>() base.OnModelCreating(modelBuilder); modelBuilder.HasDefaultSchema("devtips_multitenancy");protected override void OnModelCreating(ModelBuilder modelBuilder)
{
modelBuilder.Entity<User>()
.HasQueryFilter(x => x.TenantId.Equals(TenantProvider.GetCurrentTenantInfo().TenantId));
.HasQueryFilter(x => x.TenantId.Equals(TenantProvider.GetCurrentTenantInfo().TenantId));
.HasQueryFilter(x => x.TenantId.Equals(TenantProvider.GetCurrentTenantInfo().TenantId));
modelBuilder.ApplyConfigurationsFromAssembly(typeof(BookConfiguration).Assembly);
}
It is important to specify HasQueryFilter before calling base.OnModelCreating(modelBuilder);.
Whenever you add a new entity in your project, simply add a new query filter and all read operations for this entity will be filtered accordingly by a user's tenant. This ensures that a user will only have access to their own data.
"It is crucial to work with TenantProvider with a public property, otherwise EF Core Global Query Filters won't be applied correctly per each request.
Implementing multitenancy for write operations in EF Core
We can override SaveChangesAsync method in EF Core DbContext to implement multitenancy for write operations:
var modifiedTenantEntries = ChangeTracker.Entries<ITenantEntity>() foreach (var entry in modifiedTenantEntries) return await base.SaveChangesAsync(cancellationToken);public override async Task<int> SaveChangesAsync(CancellationToken cancellationToken = new())
{
var tenantInfo = TenantProvider.GetCurrentTenantInfo();
.Where(x => x.State is EntityState.Added or EntityState.Modified);
{
entry.Entity.TenantId = tenantInfo.TenantId
?? throw new InvalidOperationException($"Tenant id is required but was not provided for entity '{entry.Entity.GetType()}' with state '{entry.State}'");
}
}
We iterate over a list of tenant entities and automatically set the TenantId property. If a tenant identifier is not available for any reason - an exception is thrown and the operation is aborted. A tenant identifier is required to be set whenever we create, update or delete an entity.
Now let's explore multitenancy in action.
Adding tenant identifier to user claims on a login
When a user logs in, we need to use an IgnoreQueryFilters method to be able to search for a user in every tenant:
private static async Task<IResult> Handle( if (user is null) var token = GenerateJwtToken(user, jwtSettingsOptions.Value);public class LoginUserEndpoint : ICarterModule
{
public void AddRoutes(IEndpointRouteBuilder app)
{
app.MapPost("/api/users/login", Handle);
}
[FromBody] LoginUserRequest request,
ApplicationDbContext context,
IOptions<AuthConfiguration> jwtSettingsOptions,
CancellationToken cancellationToken)
{
var user = await context.Users
.IgnoreQueryFilters()
.FirstOrDefaultAsync(u => u.Email == request.Email, cancellationToken);
{
return Results.NotFound("User not found");
}
return Results.Ok(new { Token = token });
}
}
This method disables all query filters applied to a User entity. After a user is found, you need to add a "tenant-id" claim:
var claims = new[] var token = new JwtSecurityToken( return new JwtSecurityTokenHandler().WriteToken(token);private static string GenerateJwtToken(User user, AuthConfiguration auth)
{
var securityKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(auth.Key));
var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);
{
new Claim(JwtRegisteredClaimNames.Sub, user.Email),
new Claim("use-id", user.Id.ToString()),
new Claim("tenant-id", user.TenantId?.ToString() ?? string.Empty)
};
issuer: auth.Issuer,
audience: auth.Audience,
claims: claims,
expires: DateTime.Now.AddMinutes(30),
signingCredentials: credentials
);
}
Now that the user is logged in, we can start calling other endpoints with a JWT token.
Implementing API endpoints for a multitenant entity
Let's explore a Create and Get By Id endpoints for a book entity:
public class CreateBookEndpoint : ICarterModule private static async Task<IResult> Handle( var book = new Book context.Books.Add(book); var response = new BookResponse(book.Id, book.Title, book.Year, book.AuthorId);public sealed record CreateBookRequest(string Title, int Year, Guid AuthorId);
{
public void AddRoutes(IEndpointRouteBuilder app)
{
app.MapPost("/api/books", Handle);
}
[FromBody] CreateBookRequest request,
ApplicationDbContext context,
CancellationToken cancellationToken)
{
var author = await context.Authors.FindAsync([request.AuthorId], cancellationToken);
if (author is null)
{
return Results.BadRequest("Author not found");
}
{
Id = Guid.NewGuid(),
Title = request.Title,
Year = request.Year,
AuthorId = request.AuthorId,
Author = author
};
await context.SaveChangesAsync(cancellationToken);
return Results.Created($"/api/books/{book.Id}", response);
}
}
private static async Task<IResult> Handle( if (book is null) var response = new BookResponse(book.Id, book.Title, book.Year, book.AuthorId);public class GetBookByIdEndpoint : ICarterModule
{
public void AddRoutes(IEndpointRouteBuilder app)
{
app.MapGet("/api/books/{id}", Handle);
}
[FromRoute] Guid id,
ApplicationDbContext context,
CancellationToken cancellationToken)
{
var book = await context.Books
.Include(b => b.Author)
.FirstOrDefaultAsync(b => b.Id == id, cancellationToken);
{
return Results.NotFound();
}
return Results.Ok(response);
}
}
As you may have expected, with code doesn't know anything about Tenants. And it is what we were striving for — to create a secure implementation that will now allow customers to interact with another customer's data. Without a need to worry about tenants in each database call.
When creating a book, we check if an Author exists in the database by a provided AuthorId in the request. And EF Core makes sure that we can't add a Book using an Author from another tenant. Amazing!
Using tenant Id header
In some applications a user can have access to multiple tenants, for example, a "super-admin" user that can manage entities for different tenants. In such a case we need to send "X-TenantId" header in each request from the frontend (or another application) whenever we need to retrieve or modify data.
If you have such a case, you can modify your TenantProvider as follows:
public TenantProvider(IHttpContextAccessor accessor) Guid? userId = Guid.TryParse(userIdValue, out var guid) ? guid : null; if (accessor.HttpContext?.Request.Headers.TryGetValue("X-TenantId", out var headerGuid) is true) _tenantInfo = new TenantInfo(userId, headerTenantId); public TenantInfo GetCurrentTenantInfo() => _tenantInfo;public class TenantProvider : ITenantProvider
{
private readonly TenantInfo _tenantInfo;
{
var userIdValue = accessor.HttpContext?.User.FindFirstValue("user-id");
Guid? headerTenantId = null;
{
headerTenantId = Guid.Parse(headerGuid.ToString());
}
}
}
In some applications, it is preferable to always use "X-TenantId" header instead of putting it inside a JWT token. This can also be a case when you use external auth providers that have no idea about tenants.
There are different approaches to solving this problem. I will show you one possible solution with a middleware that checks if a user has access to "X-TenantId". If a user doesn't have access to the requested tenant, a 403 Forbidden response is returned.
if (!context.Request.Headers.TryGetValue("X-TenantId", out var headerGuid)) if (tenantClaimValue.Contains(headerGuid.ToString(), StringComparison.Ordinal)) var problemDetails = new ProblemDetails context.Response.StatusCode = problemDetails.Status.Value; await context.Response.WriteAsJsonAsync(problemDetails);public class TenantCheckerMiddleware : IMiddleware
{
public async Task InvokeAsync(HttpContext context, RequestDelegate next)
{
var tenantClaimValue = context.User.Claims.FirstOrDefault(x => x.Type.Equals("tenant-id"))?.Value;
if (tenantClaimValue is null)
{
await next(context);
return;
}
{
await next(context);
return;
}
{
await next(context);
return;
}
{
Status = StatusCodes.Status403Forbidden,
Title = "Bad Request",
Detail = "X-TenantId header contains a tenant id that a user doesn't have access to"
};
context.Response.ContentType = "application/problem+json";
}
}
In this example, I made a basic check if "X-TenantId" header matches the "tenant-id" from the JWT token. In your case, you might want to check in a database, or even better in a cache.
Conditional Global Query Filters
Unfortunately, EF Core doesn't support Global Query Filters with conditions, though it is a highly requested feature.
For example, you may want to implement the following query filter that will only be applied when a user has a limited access to tenants. While a "super-admin" user can view all the tenants.
if (!TenantProvider.GetCurrentTenantInfo().IsSuperAdmin)
{
builder.Entity<User>()
.HasQueryFilter(x => x.TenantId.Equals(TenantProvider.GetCurrentTenantInfo().TenantId));
}
If you try to test this application, your filters won't trigger even for a regular user. All because DbContext OnModelCreating method is only called once per lifetime of the application — when the first DbContext instance is created.
If you absolutely need to use such Global Query Filters that are applied conditionally depending on each request, you can create a DynamicModelCacheKeyFactory:
public object Create(DbContext context)public class DynamicModelCacheKeyFactory : IModelCacheKeyFactory
{
public object Create(DbContext context, bool designTime)
=> context is ApplicationDbContext dynamicContext
? (context.GetType(), dynamicContext.TenantProvider.GetCurrentTenantInfo(), designTime)
: context.GetType();
=> Create(context, false);
}
You need to replace a standard IModelCacheKeyFactory with a dynamic one when registering a DbContext:
options.EnableSensitiveDataLogging() options.ReplaceService<IModelCacheKeyFactory, DynamicModelCacheKeyFactory>();builder.Services.AddDbContext<ApplicationDbContext>((provider, options) =>
{
var interceptor = provider.GetRequiredService<AuditableInterceptor>();
.UseNpgsql(connectionString, npgsqlOptions =>
{
npgsqlOptions.MigrationsHistoryTable("__MyMigrationsHistory", "devtips_multitenancy");
})
.AddInterceptors(interceptor)
.UseSnakeCaseNamingConvention();
});
This DynamicModelCacheKeyFactory tells EF Core not to cache a created model (mapping with query filters) and call OnModelCreating method for every instance of DbContext. This ensures that conditional Global Query Filters work, but this approach severely damages the performance of each database call within a DbContext. So use this carefully and benchmark your requests.
Hope you find this blog post useful. Happy coding!
You can download source code for this blog post for free
