In this article, we will look at a sample application, EasyOA, to illustrate how to design a single instance multi-tenant enablement architecture. EasyOA is a simple office automation application developed for small businesses. We will introduce the multi-tenant design patterns for several kinds of primary sharing resources. Furthermore, a series of developerWorks articles will be published soon to address more detailed information for each topic discussed in following sections of this article.
Multi-tenant authentication and authorization mechanism
This section focuses on resolving two problems: (1) How to design the organizational data storage/access pattern in a multi-tenant context, and implement corresponding tenant-aware authentication mechanism; and (2) How to enhance the Java Authentication and Authorization Service (JAAS)-based authorization mechanism to allow tenants access and customize their specific access control lists and privileges in an isolated way.
Figure 1. Multi-tenant authentication and authorization architecture
As illustrated in Figure 1, there are four main components in the architecture we proposed to implement the authentication and authorization mechanism in the multi-tenant application.
- The tenants’ organization structures and access control data are stored in a Lightweight Directory Access Protocol (LDAP) server and a database server respectively with a multi-tenant tree schema and data models;
- An authentication service allows tenant users to login to the application and maintains the tenant-related information of current login users in the security session token;
- An authorization service supports the runtime permission validation of current login tenant users;
- A utilization service support tenants to maintain and configure their specific organization structure and access control data.
Multi-tenant Organization Structure Design and Authentication Process
Each tenant is assigned a unique tenant ID and a sub-tree of the organization structure stored in a shared LDAP server isolated by the tenant ID during on-boarding. In practical, the sub-tree may be implemented as physical or virtual.
The following images (Figures 2-4) show the EasyOA multi-tenant organization structure in the LDAP server
Figure 2. Virtualized multi-tenant organization structure tree
Figure 3. Screen shot of EasyOA virtualized organization structure in LDAP server
Figure 4. Physical multi-tenant organization structure tree
Figures 2 and 3 represent a virtualized organization structure implementation, in which the authentication process in a multi-tenant context is as follows:
- In the login page, the tenant user inputs his user name and password with tenant name provided either explicitly by input or implicitly by URL. When submitted, the login page combines the TenantName and UserName together as the userSecurityName string that IBM WebSphere Application Server (WAS) can understand, and call the WAS login module via API or form.
- The WAS login module will call the WAS LDAP User Registry to do authentication, e.g. validate the user/password via the tenant’s corresponding sub-tree of the organization structure stored in the LDAP server.
Once passing the authentication, the WAS login module creates a security session token, and stores the current login user’s tenant and session information (e.g. Tenant Name, Tenant ID, User Name, User ID, privileges etc) inside, which can be accessed by other modules of the EasyOA application in runtime easily via calling the authentication service API.
While in the physical organization structure implementation showed in Figure 4, each tenant owns a dedicated sub-tree in the LDAP server. In this case, we can leverage the new Virtual Member Manager (VMM) function provided by WAS v6.1 – the federated user repository.
In essence, this feature provides the ability to map entries from multiple individual user repositories of different tenants into a single virtual repository through configuration -- rather than development. Each repository may be an entire external repository or, in the case of LDAP, a sub-tree within that repository. The root of each repository is mapped to something called a base entry within the federated repository, which is basically a starting point within the hierarchical namespace of the virtual realm. For more information, you may refer to the article, IBM WebSphere Developer Technical Journal: Expand your user registry options with a federated repository in WebSphere Application Server V6.1, in the Resources section.
Multi-tenant permission data model design and authorization process
Figure 5 illustrates a flexible multi-tenant access a control design model based on the standard JAAS specification.
Figure 5. The multi-tenant access control model
The atom privileges are grouped into a set called privilegeGroup. Roles and users are isolated among tenants by introducing a new tenant object. Based on the model, the tenant administrators can flexibly define its specific roles, the mapping relationships of role and PrivilegeGroup, and the relationships of the role and user via the A&A Utilization Service.
When a user logins to EasyOA, the WAS user registry plug-in will retrieve all the Atom privileges the login user owns from the ACL data structure, and store them into the security session token, which will be further used by the authorization service API and other WAS components to do permission validation at runtime.
Access common J2EE artifacts in a multi-tenant context
Besides authentication and authorization, there are still many common J2EE artifacts should be isolated (cache, log, file, I/O, global static variables etc.) and customized (JSP elements like logo, login pages, log style etc.) in the multi-tenant context. In this section, we show how a simple, filter-based mechanism can help to isolate and customize these resources among tenants in an implicit way.
Figure 6. Implicit Filter based Isolation Mechanism
In this pattern illustrated in Figure 6, when the EasyOA application wants to access a certain shared resource on behalf of one tenant, it can simply raise the request as a traditional single-tenant application without needing to consider the detailed implementation of multi-tenancy of the resources access/storage. Instead of being executed directly, the request will be delegated to a common resource access module which has the privileges to access the resources of all tenants. The key to this mechanism is the delegated module which will implicitly retrieve the request owner’s tenant information from the security session token, and then compose a specific tenant-oriented filter according to some pre-defined rules. The filter will be used by the delegated module to prevent one user from tapping into resources of other tenants.
There are some typical and practical filters for different kinds of resources, for example:
- The SQL sub-statement like “where tenant_id is xxx”
- Tenant-specific log file and format with Log4j Appender
- Tenant-specific prefix for business objects in cache
- Tenant-specific file folders and files with a prefix
- The tenant-specific XML context/scope in the configuration file
- One additional tenant aware parameter or dimension of the if/then ruleset or decision table in business rule
For those resources to be customized among tenants (e.g. logo, login page, rules etc), we can build a repository to extract and store the metadata of configurable points in a tenant isolation way. Then the delegated module can easily compose the filter and access corresponding resources by leveraging the tenant awareness configuration services based on the repository. Figures 7 and 8 show EasyOA in this regard.
Figure 7. Login page customization among tenants
Figure 8. Static variables isolation among tenants
Multi-tenant data tier design patterns
This section introduces the multi-tenant architecture design and concerns in data tier by showing a variety of design patterns that include resource sharing, security isolation and customization aspects. For more information, you may refer to the article, Data Integration and Composite Business Services, Part 3: Build a multi-tenant data tier with access control and security, which is linked to in the Resources section.
Data tier resource sharing patterns
As shown in Figure 9, there are three levels of resource sharing in data tier.
- Totally isolated: Separate databases per tenant
- Partially shared: Shared database, separate schema
- Totally shared: Same database, same schema
Figure 9. Data tier resource sharing patterns in the multi-tenant context
Data tier security isolation patterns
In a multi-tenant context, the security isolation mechanism is very important in preventing the data of one tenant from being accessed illegally by other tenants. Considering the shared schema/tables pattern, there are generally two kinds of access control isolation approaches, as illustrated in Figure 10.
- Application level access control: All tenants share a common delegated database account and own the privileges to access all data for a particular tenant in the shared tables. A filter (e.g., SQL statement sub-clause) is used to filter out data records not belonging to the current tenant.
- DBMS level access control: Each tenant accesses his dedicated database or table schemas with his dedicate account via leveraging DB2 security features like lattice-based access control (LBAC). This approach can completely eliminate the potential SQL injection attack.
Figure 10. Data tier security isolation pattern in the multi-tenant context
Data tier customization patterns
In data customization aspect, there are also various degrees of flexibility for a multi-tenant application that ranges from complex schema customization to simple field extension. Obviously, for the dedicated database or table/schema isolation patterns, this is not an issue since the tenants have their separated schemas. The changes of the data model of one tenant can be made directly to its specific database/tables without impact to other tenants. However, for the shared table/schema isolation pattern, because it is shared, it can only support data field extension, whose degree of flexibility is usually measured by the maximum number of extension fields. The main implementation patterns are illustrated in Figures 11 - 13, which are the three customization patterns in a shared table/schema model. These include the following elements:
- Reserved extended table field: Pre-define a fixed number of additional data columns in each table with a generic column type (e.g. varchar).
- Dynamic extended sub-table: A sub-table, which associates with the main table via the record ID column, is built to store all the extended fields of the records in the main table.
- XML extended table field: This approach leverages the new XML features provided by DB v9. All extended data are stored in a single XML field.
Figure 11. Reserved extended table field pattern
Figure 12. Dynamic Extended Sub-table Pattern
Figure 13. XML extended table field
As we indicated above, the easyOA application is designed to support a large number (thousands) of small companies, each one with a relatively small data size. Therefore, EasyOA takes use of the shared table/schema pattern to reduce cost. The MDC (multiple dimension clustering) technology (please see the Resources section for more information) is applied to improve the performance in this sharing pattern. EasyOA further leverages LBAC to implement DBMS level security, so as to prevent invalid data access among tenants. For the customization requirements, it takes a hybrid pattern: several fixed data fields are reserved for each table in default, but still support the sub-table pattern. This approach has obvious merits. It can provide both good performance for tenants with limited customization requirements, and more flexibility for those tenants who need more extended fields.
Isolate and customize people/role selection rules of business process
In the business process/workflow tier, the process templates are the most important resources. To support multi-tenant application development, there are two kinds of options:
- Separate Process Templates Pattern: In this situation, each tenant owns a dedicated set of process templates. The access requests of a certain tenant should be routed or dispatched to its corresponding process templates or instances. This approach is easier to do isolation and customization in the tenant level. However, it has obvious cost issues. For example, if an application owns 20 BPEL processes, to support 1,000 tenants, there should be over 20,000 process templates.
- Shared Process Templates Pattern: All tenants share the same set of process templates. This is the approach we will take. Its challenge is how to isolate and customize those shared process related artifacts like human task verb, business rule, and process skeleton.
This section describes a specific staff resolution isolation mechanism for process template and human task, which can automatically and transparently select corresponding roles/persons belonging to the same tenant with the process starter. It can also support one tenant customizing his own staff resolution rules without impacting other tenants.
In WebSphere Process Server, the “Verb” is used to do the people/role selection of the human task or process. In runtime, the “Verb” is resolved by the “Staff Resolution Plug-in” by parsing the parameters and querying the underlying users’ repository to choose appropriate roles. Generally, there are three kinds of Staff Resolution Plug-ins shipped with WPS, System, LDAP, UR, and some standard “Verbs” like “User, Group Members, Search etc.” in default.
However, in the multi-tenant context, if all tenants share the same set of process templates, the standard verbs and plug-ins can’t work well since they don’t understand the underlying multi-tenant organizational structure and user repository.
Figure 14 illustrates our approaches to resolve this problem from design-time, run-time and management aspects:
- In build time, we provide a set of multi-tenant enabled verbs and one corresponding multi-tenant staff resolution plug-in for developers to leverage them to design the process templates.
- In the runtime, the specific designed plug-in will first get the user ID and corresponding tenant ID of the starter of the process instance, and then query the people/roles from the organizational structure within the tenant’s specific scope. To be noted, all of these are executed in an implicit way.
- In management aspect, the administrator of one tenant can easily customize his specific people/roles selection rules for any process or human task by choosing from a set of pre-defined rules, without impacting other tenants.
Figure 14. Multi-tenant verbs and staff resolution plug-in
Figures 15 and 16 show EasyOA in the process tier to show the result of leveraging the isolation and customization mechanism that we discussed previously.
Figure 15. People/Roles Selection Isolation
Figure 16. People/Roles Selection Customization
The multi-tenant design pattern (e.g., using a single shared application instance to support multiple tenants simultaneously) is very important to the Web-deliverable applications in terms of cost effectiveness. This article addressed the architecture design of the single instance multi-tenant application. We introduced the multi-tenant design patterns from four different aspects including security mechanism, J2EE artifacts, data model and business process. More information will be further introduced in several forthcoming articles.
- The IBM SOA Web site offers an overview of SOA and how IBM can help you get there.
- developerWorks article, "Develop and deploy multi-tenant Web-delivered solutions using IBM middleware, Part 1: Challenges and architectural patterns" provides a overall introduction to the multi-tenant web delivered solution development.
- developerWorks article, "Develop and deploy the multi-tenant web delivered solutions using IBM middleware, Part II: Resource sharing, isolation and customization in the single instance multi-tenant application".
- developerWorks article, "J2EE pathfinder: Java security with JAAS and JSSE" provides a short introduction to the J2EE Web application security architecture.
- Find Java security technology resources on Java.sun.com.
- "IBM WebSphere Developer Technical Journal: Expand your user registry options with a federated repository in WebSphere Application Server V6.1", (developerWorks, Jan 2007).
- "Data Integration and Composite Business Services, Part 3: Build a multi-tenant data tier with access control and security", (developerWorks, Dec 2007).
- "IBM DB2 Database for Linux, UNIX, and Windows Information Center", find all online DB2 9.5 product manuals for Linux, UNIX, and Windows.
- "DB2 Label-Based Access Control, a practical guide, Part 1: Understand the basics of LBAC in DB2", (developerWorks, May 2006): Learn how to use DB2's LBAC feature.
- IBM WebSphere Process Server Information Center for Multiple platforms v6.0.x.