Creating a SaaS App with the Multi-Tenant Carbon Framework – Step 1

  • By Chris Haddad
  • 17 Sep, 2013

Because WSO2 Carbon based middleware servers contain a tenancy framework, development teams may rapidly migrate single-tenant web applications into multi-tenant SaaS applications. WSO2 Carbon creates a multi-tenant environment inside the middleware servers (i.e. application server, integration server, Enterprise Service Bus) and delivers unparalleled tenant density. For more information on the cost and effort savings, read the multi-tenant, shared container PaaS white paper.

The WSO2 Carbon framework creates tenant partitions, registers tenant specific applications, provides tenant administration tools, and holds run-time tenant context.

In this blog post series, we will deploy a tenant-aware SaaS application on the WSO2 Application Server 5.1, illustrate how to acquire the Carbon Context object, and demonstrate multi-tenancy in action. The WSO2 Application Server is based on Apache Tomcat, and extends Tomcat with enterprise security, logging, management, clustering, and multi-tenancy; turning the open source Apache Tomcat project into Enterprise, Cloud-Native Tomcat++

Step 1 – Deploy Carbon and Acquire Carbon Context

The SaaS application demonstrates tenant-specific framework objects, illustrates tenancy isolation, and reviews the Java Tenancy API within WSO2 Carbon. The application code is available from GitHub at

The Carbon Context object holds registry, cache, queue, user realm, and role based access control (RBAC) information for each tenant run-time context. Each SaaS application can use a Carbon platform API to access context details and personalize the application experience.

This blog tutorial and example code demonstrates the following getting started concepts and steps:

  • Getting Started #1 – Defining a Tenancy Dimension Model
    • Step 0: Deploy the WSO2 Application Server and start server
    • Step 1: Log into the Carbon administration console as the super-administrator
  • Getting Started #2 – Provisioning SaaS Applications
    • Step 0: Compile the CarbonSaaSTest Application
    • Step 1: Provision a Global Tenant Scope SaaS Application
  • Getting Started #3 – Acquire Tenant Context

Getting Started #1 – Defining a Tenancy Dimension Model

When building a SaaS application, the first step is to define your tenancy dimension model. In WSO2 Carbon, each organization, department, user, or application may be defined as a unique tenant realm. When determining the appropriate tenancy dimension model, consider tenant information isolation/access and delegated administration benefits.

The PaaS super-administrator can define multiple administrators per tenant realm. Tenant administrators may delegate application management, API management, access control, role management, log management, and user management within the tenant realm.

Code deployed within a tenant realm will share registry, cache, queue, and user realm information.

For this example, we will define tenancy at the organization level. As a result, Carbon will personalize context at the organization level. For example, a single application codebase will access organization-specific users, rules, processes, and data depending upon who logs into the application. When choosing organizational tenancy, isolating information across users within a tenant realm must be performed by additional application-level code.

WSO2 Carbon provides a unique ability to host multiple tenant realms within a single application server, and also provides a differentiating capability to subscribe tenants to applications. To minimize run-time footprint and optimize resource efficiency, this tutorial will host multiple tenants within a single application server. The tutorial steps will demonstrate restricting an application to a single tenant domain, or deploying an application for use by all tenants.

When administrators deploy an application into a single tenant domain, the server run-time is shared, and shared application code is personalized per tenant. Carbon isolates users, roles, cache, and registry information per tenant domain without explicitly requiring separate deployment of repositories or servers.

The traditional web application personalization analogue is using resource bundles to personalize the user experience. WSO2 Carbon delivers advantages over Java resource bundles. Using the WSO2 Carbon Multi-tenancy framework, resources are inherently keyed by tenant domain, and the OSGI security manager implicitly enforces resource isolation and tenant access.

We will also deploy a multi-tenant SaaS application that is shared by all tenants. Each tenant organization will access common business capabilities offered by the multi-tenant SaaS application. The shared SaaS application minimizes administration and centralizes usage.

Step 0: Deploy the WSO2 Application Server and start server

1.Download the WSO2 Application Server (version 5.1) from

2.Unzip the distribution

3.Navigate to Application Server home directory and run startup script

./bin/   or ./bin/wso2server.bat

Step 1: Log into the Carbon administration console as the super-administrator

1. Access Console URL in your web browser:


2. Enter Default super-administrator username and password

admin : admin

Step 2: Create two tenant domains

1. Navigate to the ‘Configure’ Tab, ‘Multitenancy’ section, and choose ‘Add New Tenant’

2. Enter domain information, tenant administration credentials, and contact information.

For our example, we chose the following:

Tenant Domain Tenant Administrator User Name [email protected] [email protected]

You now have two organizations defined as distinct tenant domains within a single application server resource (or resource cluster).

Logout of the administrator console, log in as a tenant domain administrator, and create a few tenant domain users. For the users, associate the ‘everyone’ role, or associate your own custom role and role permissions.

Getting Started #2 – Provisioning SaaS Applications

SaaS applications may be provisioned within tenant domain scope or global scope. When determining the appropriate provisioning scope, consider the following decision matrix:

Tenant Domain Scope Global Domain Scope
A separate URL for each Tenant Application. Example,https://localhost:9763/t/ Single, common application URL for All Tenants. Example,https://localhost:9763/SaasTest-1.0.0/
Tenant administrators control application lifecycle, security, and application configuration. Service provider administrators control application lifecycle, security and application configuration

In both scenarios, a user’s associated tenant domain and user role determine user access to application. In both scenarios, the WSO2 Carbon framework segregates tenant specific cache, registry, JNDI context, and queues based on the user’s tenant context.

Step 0: Compile the SaaSTest Application

1. Clone the application codebase from GitHub.

2.Enable multi-tenancy for the application. To turn on tenancy, edit the web.xml file and adding the appropriate element (if not existing). Replace the [VALUE] for the carbon.saas.tenants parameter with the appropriate tenant scope.


Associate All Tenants with Application


3. Run the build script to build the executable target

mvn clean install

While creating this tutorial, the CarbonSaaSTest sample code was built with Java version “1.6.0_51″ and Apache Maven 3.0.4 (r1232337; 2012-01-17 03:44:56-0500).

Step 1: Provision a Global Scope Application

  1. Login to the Administrator console as the super-tenant administrator. After logon, verify the signed-in user as [email protected] by viewing the upper left corner of the browser window.
  2. Navigate to ‘Main’ tab, ‘Application | Applications’ section, and choose the ‘Add Web Application’ action.
  3. Upload the {CarbonSaaSTest-home}/target/SaaSTest-1.0.0.war file.
  4. Navigate to ‘Main’ tab, ‘Application | List’ section and verify the application is properly listed.
  5. In the actions column, click on the ‘Go To URL’ link to access the application. Login with service provider administrator, tenant administrator, or tenant domain user credentials.

Getting Started #3 – Acquire Tenant Specific Context

In this phase, the tutorial will demonstrate how Carbon maintains registry, cache, queue, user realm, and role based access control (RBAC) information for each tenant run-time context.

Tenant specific instances (e.g. registry, cache, queue, user realm, user information) are obtained from the org.wso2.carbon.context.CarbonContext framework class. The following code illustrates accessing the tenant specific context objects:

CarbonContext cCtx = CarbonContext.getCurrentContext();
Tenant Specific Object SaaS Application Code
Tenant Identifier int tenantId = cCtx.getTenantId();
Tenant Domain String tenantDomain = cCtx.getTenantDomain();
Tenant UserName String tenantUsername = cCtx.getUsername();
Tenant Specific Registry Registry tRegistry = cCtx.getRegistry(RegistryType);
Tenant Specific User Realm UserRealm tUserRealm = cCtx.getUserRealm();
Tenant Specific Cache Cache tCache = cCtx.getCache(String cacheName);
Tenant Specific Queu CarbonQueue tQueue = cCtx.getQueue(String name);
Tenant Specific JNDI Context Context tContet = cCtx.getJNDIContext();

The next blog post will demonstrate how /context/context.jsp and /usermgt/usermgt.jsp initializes the tenant specific context objects, and how /view/view.jsp and /usermgt/usermgt.jsp reads and displays tenant specific context object values.

Recommended Reading

Building a Multi-Tenant SaaS Application Introduction.

Building a SaaS Application Webinar.