imhven
/
abp
mirror of https://github.com/abpframework/abp
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Revised the multi-tenancy doc.

Browse Source
pull/5585/head
Halil İbrahim Kalkan 5 years ago
parent 51019aa0e2
commit feb0e16ba9
2 changed files with 199 additions and 116 deletions
Show Stats Download Patch File Download Diff File

2
docs/en/Modules/Identity.md
Unescape View File

@ -2,7 +2,7 @@
Identity module is used to manage [organization units](Organization-Units.md), roles, users and their permissions, based on the Microsoft Identity library.
See [the source code](https://github.com/abpframework/abp/tree/dev/modules/identity). Documentation will come soon...
**See [the source code](https://github.com/abpframework/abp/tree/dev/modules/identity). Documentation will come soon...**
## Identity Security Log

313
docs/en/Multi-Tenancy.md
Unescape View File

@ -1,148 +1,271 @@
## Multi-Tenancy
# Multi-Tenancy
ABP Multi-tenancy module provides base functionality to create multi tenant applications.
Multi-Tenancy is a widely used architecture to create **SaaS applications** where the hardware and software **resources are shared by the customers** (tenants). ABP Framework provides all the base functionalities to create **multi tenant applications**.
Wikipedia [defines](https://en.wikipedia.org/wiki/Multitenancy) multi-tenancy as like that:
Wikipedia [defines](https://en.wikipedia.org/wiki/Multitenancy) the multi-tenancy as like that:
> Software **Multi-tenancy** refers to a software **architecture** in which a **single instance** of software runs on a server and serves **multiple tenants**. A tenant is a group of users who share a common access with specific privileges to the software instance. With a multitenant architecture, a software application is designed to provide every tenant a **dedicated share of the instance including its data**, configuration, user management, tenant individual functionality and non-functional properties. Multi-tenancy contrasts with multi-instance architectures, where separate software instances operate on behalf of different tenants.
### Volo.Abp.MultiTenancy Package
## Terminology: Host vs Tenant
Volo.Abp.MultiTenancy package defines fundamental interfaces to make your code "multi-tenancy ready". So, install it to your project using the package manager console (PMC):
There are two main side of a typical SaaS / Multi-tenant application:
````
Install-Package Volo.Abp.MultiTenancy
````
* A **Tenant** is a customer of the SaaS application that pays money to use the service.
* **Host** is the company that owns the SaaS application and manages the system.
> This package is already installed by default with the startup template. So, most of the time, you don't need to install it manually.
We will use the Host and Tenant terms for that purpose in the rest of the document.
Then you can add **AbpMultiTenancyModule** dependency to your module:
## IMultiTenant
````C#
using Volo.Abp.Modularity;
You should implement the `IMultiTenant` interface for your [entities](Entities.md) to make them **multi-tenancy ready**.
**Example: A multi-tenant *Product* entity**
````csharp
using System;
using Volo.Abp.Domain.Entities;
using Volo.Abp.MultiTenancy;
namespace MyCompany.MyProject
namespace MultiTenancyDemo.Products
{
[DependsOn(typeof(AbpMultiTenancyModule))]
public class MyModule : AbpModule
public class Product : AggregateRoot<Guid>, IMultiTenant
{
//...
public Guid? TenantId { get; set; } //Defined by the IMultiTenant interface
public string Name { get; set; }
public float Price { get; set; }
}
}
````
> With the "Multi-tenancy ready" concept, we intent to develop our code to be compatible with multi-tenancy approach. Then it can be used in a multi-tenant application or not, depending on the requirements of the final application.
* `IMultiTenant` interface just defines a `TenantId` property.
#### Define Entities
When you implement this interface, ABP Framework **automatically** [filters](Data-Filtering.md) entities for the current tenant when you query from database. So, you don't need to manually add `TenantId` condition while performing queries; a tenant can not access to data of another tenant.
You can implement **IMultiTenant** interface for your entities to make them multi-tenancy ready. Example:
### Why the TenantId Property is Nullable?
````C#
`IMultiTenant.TenantId` is **nullable**. When it is null that means the entity is owned by the **Host** side and not owned by a tenant. It is useful when you create a functionality in your system that is both used by the tenant and the host sides.
For example, `IdentityUser` is an entity defined by the [Identity Module](Modules/Identity.md). The host and all the tenants have their own users. So, for the host side, users will have a `null` `TenantId` while tenant users will have their related `TenantId`.
> **Tip**: If your entity is tenant-specific and has no meaning in the host side, you can force to not set `null` for the `TenantId` in the constructor of your entity.
### When to set the TenantId?
ABP Framework doesn't set the `TenantId` for you (because of the cross tenant operations, ABP can not know the proper `TenantId` in some cases). So, you need to set it yourself **when you create a new multi-tenant entity**.
#### Best Practice
We suggest to set the `TenantId` in the constructor and never allow to change it again. So, the `Product` class can be re-written as below:
````csharp
using System;
using Volo.Abp.Domain.Entities;
using Volo.Abp.MultiTenancy;
namespace MyCompany.MyProject
namespace MultiTenancyDemo.Products
{
public class Product : AggregateRoot, IMultiTenant
public class Product : AggregateRoot<Guid>, IMultiTenant
{
public Guid? TenantId { get; set; } //IMultiTenant defines TenantId property
//Private setter prevents changing it later
public Guid? TenantId { get; private set; }
public string Name { get; set; }
public float Price { get; set; }
protected Product()
{
//This parameterless constructor is needed for ORMs
}
public Product(string name, float price, Guid? tenantId)
{
Name = name;
Price = price;
TenantId = tenantId; //Set in the constructor
}
}
}
````
IMultiTenant requires to define a **TenantId** property in the implementing entity (See [entity documentation](Entities.md) for more about entities).
> You can see the [entities document](Entities.md) for a more about entities and aggregate roots.
#### Obtain Current Tenant's Id
You typically use the `ICurrentTenant` to set the `TenantId` while creating a new `Product`.
Your code may require to get current tenant's id (regardless of how it's retrieved actually). You can [inject](Dependency-Injection.md) and use **ICurrentTenant** interface for such cases. Example:
**Example: Creating a new product in a [Domain Service](Domain-Services.md)**
````C#
using Volo.Abp.DependencyInjection;
using Volo.Abp.MultiTenancy;
````csharp
using System;
using System.Threading.Tasks;
using Volo.Abp.Domain.Repositories;
using Volo.Abp.Domain.Services;
namespace MyCompany.MyProject
namespace MultiTenancyDemo.Products
{
public class MyService : ITransientDependency
public class ProductManager : DomainService
{
private readonly ICurrentTenant _currentTenant;
private readonly IRepository<Product, Guid> _productRepository;
public MyService(ICurrentTenant currentTenant)
public ProductManager(IRepository<Product, Guid> productRepository)
{
_currentTenant = currentTenant;
_productRepository = productRepository;
}
public void DoIt()
public async Task<Product> CreateAsync(string name, float price)
{
var tenantId = _currentTenant.Id;
//use tenantId in your code...
var product = new Product(name, price, CurrentTenant.Id);
return await _productRepository.InsertAsync(product);
}
}
}
````
#### Change Current Tenant
* `DomainService` base class (and some common base classes in the ABP Framework) provides the `CurrentTenant`, so you directly use it. Otherwise, you need to [inject](Dependency-Injection.md) the `ICurrentTenant` service.
TODO: ...
## ICurrentTenant
#### Determining Current Tenant
`ICurrentTenant` is the main service to interact with the multi-tenancy infrastructure. `ApplicationService`, `DomainService`, `AbpController` and some other base classes already has pre-injected `CurrentTenant` properties. For other type of classes, you can inject the `ICurrentTenant` into your service.
The first thing for a multi-tenant application is to determine the current tenant on the runtime. Volo.Abp.MultiTenancy package only provides abstractions (named as tenant resolver) for determining the current tenant, however it does not have any implementation out of the box.
### Tenant Properties
**Volo.Abp.AspNetCore.MultiTenancy** package has implementation to determine the current tenant from current web request (from subdomain, header, cookie, route... etc.). See Volo.Abp.AspNetCore.MultiTenancy Package section later in this document.
`ICurrentTenant` defines the following properties;
##### Custom Tenant Resolvers
* `Id` (`Guid`): Id of the current tenant. Can be `null` if the current user is a host user or the tenant could not be determined from the request.
* `Name` (`string`): Name of the current tenant. Can be `null` if the current user is a host user or the tenant could not be determined from the request.
* `IsAvailable` (`bool`): Returns `true` if the `Id` is not `null`.
You can add your custom tenant resolver to **AbpTenantResolveOptions** in your module's ConfigureServices method as like below:
### Change the Current Tenant
````C#
using Microsoft.Extensions.DependencyInjection;
using Volo.Abp.Modularity;
using Volo.Abp.MultiTenancy;
ABP Framework automatically filters the resources (database, cache...) based on the `ICurrentTenant.Id`. However, in some cases you may want to perform an operation on behalf of a specific tenant, generally when you are in the host context.
namespace MyCompany.MyProject
`ICurrentTenant.Change` method changes the current tenant for a limited scope, so you can safely perform operations for the tenant.
**Example: Get product count of a specific tenant**
````csharp
using System;
using System.Threading.Tasks;
using Volo.Abp.Domain.Repositories;
using Volo.Abp.Domain.Services;
namespace MultiTenancyDemo.Products
{
[DependsOn(typeof(AbpMultiTenancyModule))]
public class MyModule : AbpModule
public class ProductManager : DomainService
{
public override void ConfigureServices(ServiceConfigurationContext context)
private readonly IRepository<Product, Guid> _productRepository;
public ProductManager(IRepository<Product, Guid> productRepository)
{
Configure<AbpTenantResolveOptions>(options =>
{
options.TenantResolvers.Add(new MyCustomTenantResolveContributor());
});
_productRepository = productRepository;
}
//...
public async Task<long> GetProductCountAsync(Guid? tenantId)
{
using (CurrentTenant.Change(tenantId))
{
return await _productRepository.GetCountAsync();
}
}
}
}
````
`MyCustomTenantResolveContributor` must implement **ITenantResolveContributor** as shown below:
* `Change` method can be used in a **nested way**. It restores the `CurrentTenant.Id` to the previous value after the `using` statement.
* When you use `CurrentTenant.Id` inside the `Change` scope, you get the `tenantId` provided to the `Change` method. So, the repository also get this `tenantId` and can filter the database query accordingly.
````C#
> Always use the `Change` method with a `using` statement like done in this example.
## Determining Current Tenant
The first thing for a multi-tenant application is to determine the current tenant on the runtime. ABP Framework provides an extensible *Tenant Resolving* system for that purpose.
### Default Tenant Resolvers
The following resolvers are provided by default;
* `CurrentUserTenantResolveContributor`: Gets the tenant id from claims of the current user, if the current user has logged in. **This should always be the first contributor for the security**.
* `QueryStringTenantResolveContributor`: Tries to find current tenant id from query string parameters. The parameter name is `__tenant` by default.
* `FormTenantResolveContributor`：Tries to find current tenant id from form parameters. The parameter name is `__tenant` by default.
* `RouteTenantResolveContributor`: Tries to find current tenant id from route (URL path). The variable name is `__tenant` by default. If you defined a route with this variable, then it can determine the current tenant from the route.
* `HeaderTenantResolveContributor`: Tries to find current tenant id from HTTP headers. The header name is `__tenant` by default.
* `CookieTenantResolveContributor`: Tries to find current tenant id from cookie values. The cookie name is `__tenant` by default.
#### Problems with the NGINX
You may have problems with the `__tenant` in the HTTP Headers if you're using the [nginx](https://www.nginx.com/) as the reverse proxy server. Because it doesn't allow to use underscore and some other special characters in the HTTP headers and you may need to manually configure it. See the following documents please:
http://nginx.org/en/docs/http/ngx_http_core_module.html#ignore_invalid_headers
http://nginx.org/en/docs/http/ngx_http_core_module.html#underscores_in_headers
#### AbpAspNetCoreMultiTenancyOptions
`__tenant` parameter name can be changed using `AbpAspNetCoreMultiTenancyOptions`.
**Example:**
````csharp
services.Configure<AbpAspNetCoreMultiTenancyOptions>(options =>
{
options.TenantKey = "MyTenantKey";
});
````
> However, we don't suggest to change this value since some clients may assume the the `__tenant` as the parameter name and they might need to manually configure then.
### Domain/Subdomain Tenant Resolver
In a real application, most of times you will want to determine current tenant either by subdomain (like mytenant1.mydomain.com) or by the whole domain (like mytenant.com). If so, you can configure the `AbpTenantResolveOptions` to add the domain tenant resolver.
**Example: Add a subdomain resolver**
````csharp
Configure<AbpTenantResolveOptions>(options =>
{
options.AddDomainTenantResolver("{0}.mydomain.com");
});
````
* `{0}` is the placeholder to determine current tenant's unique name.
* Add this code to the `ConfigureServices` method of your [module](Module-Development-Basics.md).
* This should be done in the *Web/API Layer* since the URL is a web related stuff.
### Custom Tenant Resolvers
You can add implement your custom tenant resolver and configure the `AbpTenantResolveOptions` in your module's `ConfigureServices` method as like below:
````csharp
Configure<AbpTenantResolveOptions>(options =>
{
options.TenantResolvers.Add(new MyCustomTenantResolveContributor());
});
````
`MyCustomTenantResolveContributor` must inherit from the `TenantResolveContributorBase` (or implement the `ITenantResolveContributor`) as shown below:
````csharp
using Volo.Abp.MultiTenancy;
namespace MyCompany.MyProject
namespace MultiTenancyDemo.Web
{
public class MyCustomTenantResolveContributor : ITenantResolveContributor
public class MyCustomTenantResolveContributor : TenantResolveContributorBase
{
public void Resolve(ITenantResolveContext context)
public override string Name => "Custom";
public override void Resolve(ITenantResolveContext context)
{
context.TenantIdOrName = ... //find tenant id or tenant name from somewhere...
//TODO...
}
}
}
````
A tenant resolver can set **TenantIdOrName** if it can determine it. If not, just leave it as is to allow next resolver to determine it.
* A tenant resolver should set `context.TenantIdOrName` if it can determine it. If not, just leave it as is to allow the next resolver to determine it.
* `context.ServiceProvider` can be used if you need to additional services to resolve from the [dependency injection](Dependency-Injection.md) system.
#### Tenant Store
## Avdanced Topics
### Tenant Store
Volo.Abp.MultiTenancy package defines **ITenantStore** to abstract data source from the framework. You can implement ITenantStore to work with any data source (like a relational database) that stores information of your tenants.
@ -300,75 +423,35 @@ TODO:...
#### Determining Current Tenant From Web Request
Volo.Abp.AspNetCore.MultiTenancy package adds following tenant resolvers to determine current tenant from current web request (ordered by priority). These resolvers are added and work out of the box:
* **CurrentUserTenantResolveContributor**: Gets the tenant id from claims of the current user, if the current user has logged in. **This should always be the first contributor for security**.
* **QueryStringTenantResolveContributor**: Tries to find current tenant id from query string parameter. Parameter name is "__tenant" by default.
* **FormTenantResolveContributor**： Tries to find current tenant id from form parameter. Parameter name is "__tenant" by default.
* **RouteTenantResolveContributor**: Tries to find current tenant id from route (URL path). Variable name is "__tenant" by default. So, if you defined a route with this variable, then it can determine the current tenant from the route.
* **HeaderTenantResolveContributor**: Tries to find current tenant id from HTTP header. Header name is "__tenant" by default.
* **CookieTenantResolveContributor**: Tries to find current tenant id from cookie values. Cookie name is "__tenant" by default.
### Related Packages
> If you use nginx as a reverse proxy server, please note that if `TenantKey` contains an underscore or other special characters, there may be a problem, please refer to:
http://nginx.org/en/docs/http/ngx_http_core_module.html#ignore_invalid_headers
http://nginx.org/en/docs/http/ngx_http_core_module.html#underscores_in_headers
TODO
Volo.Abp.MultiTenancy package defines fundamental interfaces to make your code "multi-tenancy ready". So, install it to your project using the package manager console (PMC):
"__tenant" parameter name can be changed using AbpAspNetCoreMultiTenancyOptions. Example:
````C#
services.Configure<AbpAspNetCoreMultiTenancyOptions>(options =>
{
options.TenantKey = "MyTenantKey";
});
````
Install-Package Volo.Abp.MultiTenancy
````
##### Domain Tenant Resolver
In a real application, most of times you will want to determine current tenant either by subdomain (like mytenant1.mydomain.com) or by the whole domain (like mytenant.com). If so, you can configure AbpTenantResolveOptions to add a domain tenant resolver.
> This package is already installed by default with the startup template. So, most of the time, you don't need to install it manually.
###### Example: Add a subdomain resolver
Then you can add **AbpMultiTenancyModule** dependency to your module:
````C#
using Microsoft.Extensions.DependencyInjection;
using Volo.Abp.AspNetCore.MultiTenancy;
using Volo.Abp.Modularity;
using Volo.Abp.MultiTenancy;
namespace MyCompany.MyProject
{
[DependsOn(typeof(AbpAspNetCoreMultiTenancyModule))]
[DependsOn(typeof(AbpMultiTenancyModule))]
public class MyModule : AbpModule
{
public override void ConfigureServices(ServiceConfigurationContext context)
{
Configure<AbpTenantResolveOptions>(options =>
{
//Subdomain format: {0}.mydomain.com
//Adding as the second highest priority resolver after 'CurrentUserTenantResolveContributor' to
//ensure the user cannot impersonate a different tenant.
options.TenantResolvers.Insert(1, new DomainTenantResolveContributor("{0}.mydomain.com"));
});
//...
}
//...
}
}
````
{0} is the placeholder to determine current tenant's unique name.
Instead of ``options.TenantResolvers.Insert(1, new DomainTenantResolveContributor("{0}.mydomain.com"));`` you can use this shortcut:
````C#
options.AddDomainTenantResolver("{0}.mydomain.com");
````
###### Example: Add a domain resolver
````C#
options.AddDomainTenantResolver("{0}.com");
````
> With the "Multi-tenancy ready" concept, we intent to develop our code to be compatible with multi-tenancy approach. Then it can be used in a multi-tenant application or not, depending on the requirements of the final application.
## See Also

Write Preview
Loading…
Cancel
Save