Multi-tenant data management is core to the success of any Software as a Service application. With multi-tenancy, SaaS vendors can provide one version of their product to multiple customers instead of building a unique codebase for each one. However, giving your customer organizations a private partition of your SaaS application can be incredibly complicated to build and maintain.

Fortunately, Stormpath was designed for user management in SaaS applications. In this post, we’ll go over how to build secure customer partitions with Stormpath’s multi-tenant architecture out-of-the-box.

Simplified Multi-Tenant User Storage

Stormpath is a separate user system that allows you to connect multiple applications with a shared user base. This makes it really powerful for SaaS Applications, which is what Stormpath was designed for. Not only can you support multiple Customer Organizations within your data store, you can connect multiple applications. If you’re serving your customer a suite of products and services, you can handle their authentication seamlessly between those services, and partition their user data so that they are secure and separate from each other.

What is Multi-Tenant Authorization?

Imagine you’re building a big self-storage building. Inside your big building you build one storage unit. Now the one storage unit you’ve built and rented out is probably not going to make a profitable business for you. The great thing about storage units is that they’re easily replicated. You don’t need a new building, you already have that, and each storage unit has a lock on it granting access only to the set of people that know the combination.

Building out applications for Multi-Tenancy is similar to this. Your application is the big building. We want to grant access to specific groups that are separated from each other. These are called Organizations of people.

Multi-Tenancy models Customer Organizations. It partitions parts of your user database between separate Customer Organizations. Let’s say you’ve built a SaaS application and sold it to Purple Company and Green Company. Those user stores live in partitioned buckets.

Types of Multi-Tenant Applications

There are different three different approaches to Multi-Tenancy that you can choose from when building your application.

Manual Selection Before Authentication

This is when you have an extra field on your log in form where the user would manually type in their Organization. They might type in “Green” for the Organization that they belong to, and then enter their email and password as usual.

Manual Selection After Authentication

First the user would authenticate using their username and password. Then they land in the lobby of the application where they select their Organization from a list. The user would select the right one and go to the main part of the app.

Automatic Selection by Subdomain

This post will focus on the easiest type of Multi-Tenancy to manage for your users which is Automatic Selection by Subdomain. It’s an advanced Multi-Tenant feature supported by Stormpath. Let’s look at how to build this.

Build a Multi-Tenant Application With Automatic Selection by Subdomain

Let’s say you’re building this super sweet new WizBang app and are using Stormpath to manage your user identities. Inside of Stormpath, you’ll create a Stormpath Application backed by a Stormpath Directory. When your user wants to log into your application, they fire up their browser, go to, and authenticate.

Users see this process as a completely white label experience. They don’t need to see anything about Stormpath, just the typical authentication process that they’re used to.

Support a Separate User Organization

Next you want to support a new Organization worth of users in the same application. Without Multi-Tenancy support you’d need to replicate this architecture. You would need to have a separate instance of your application, a separate identity management system, and a separate Stormpath application. Stormpath makes Multi-Tenancy easy by letting you swap out that Directory for a core object in Stormpath called the Organizations.

Multi-Tenant Organizations in Stormpath

In Stormpath, Organizations are just a different type of Account Store. Organizations have a unique identifier called an Organization Name Key that matches up to a subdomain of your domain. That’s when you get the automatic subdomain feature of Multi-Tenancy.

multi-tenancy diagram

In this diagram there’s one Organization called Green. If we want to support another Organization named Purple, we simply create an Organization with a Name Key of Purple. It has its own directory of users without redeploying or recreating a separate application. You now have Multi-Tenant support for different Organizations of users!

How to Create Organizations in the Stormpath Console

Let’s take a look at the Stormpath Admin Console and how this works. Across the top of the Stormpath Admin Console, you’ll see the first class objects that Stormpath has to manage user identities. Organizations are first class objects in Stormpath.

First, let’s create a Stormpath Application called WizBang. This WizBang application will have Account Stores consisting of the accounts that are allowed to access this application.

account stores

You’ll see that those Organizations have a Name Key. WizBang Green should have the Name Key of “Green” and WizBang Purple should have the Name Key of “Purple”. Typing in the URL or takes us through the Account Stores of these different Organizations for authentication and authorization.

These Organizations have their own Account Stores. The Directory is where we will store the identities of users that are allowed to login. In Purple we have J. Jones, and in Green we have an account called B. Smith.


Hosted Authentication and Authorization Workflows with ID Site

ID Site is a hosted set of authentication and authorization workflows including login registration, forgot my password, change my password, etc. ID Site is powerful for multi-tenancy because it supports the idea of wild carding. For security reasons, you have to specify authorized URLs and authorized redirects. Users will hit your applications and be redirected to ID Site at login.

When they’ve successfully authenticated at ID Site, they’ll be redirected back to your application. You can put in a custom name for your domain that’s secured by your SSL key insert. Then when users are getting redirected to ID Site they only ever see your domain. They have no knowledge that Stormpath is behind the user identity management.

Multi-Tenancy in Your Application

Let’s jump into the app and see this in action. We’ll open an Incognito Window and go to Your application is already aware of the user’s Organization based on the subdomain.

green application home

When we click the login button, we’re redirected to ID Site. That is the long URL up top and can be customized as your domain.

green login

Let’s log in as B. Smith. If you remember, we created accounts in each of the Directories that back the Organizations. We see this “welcome to the Green organization” and it knows us by name. Now we’ve been redirected back into the application and successfully authenticated.

green welcome screen

If go through the same process on we’ll see the same introductory page that knows the Organization based on subdomain. We can log in as J. Jones and it knows what Organization we belong to.

However, if we try to log in to the Purple Organization as B. Smith it’s not going to let us because B. Smith does not belong to the Purple Organization.

Behind the scenes there is a single application running. That’s the power of Multi-Tenancy, you don’t have to replicate your architecture in order to support it!

Add a New Tenant to Your Organization

Let’s say you want to add a new Tenant and support a new Organization worth of users. All you need to do is to create a new Organization and map it into your application.

In the Organizations tab, we’ll create a new Organization called WizBang Blue and give it the Name Key of “Blue”.

We need to give it an Account Store just like we did for the other Organizations. We’ll set up the WizBang Blue Directory and, just like the other directories, create an Account under it.

The last step is go into the WizBang application. Add that Organization as an Organization Mapping for the application.

We’ve gone from supporting Green and Purple to now supporting Blue. Let’s go to

By updating information in the Stormpath Admin Console, we can now log in with this account and get the same Organizational partitioning by Subdomain.

add organization

It’s that easy to work with Organizations and Multi-Tenancy by Subdomain! Most of it is just configuration in the admin console, your code doesn’t have to change.

Custom Data

We don’t want to update our application every time we add new tenants. However, there may be some customizations or specialized features that you want to support based on the Organization. Stormpath’s newest feature, Custom Data, allow you to access unstructured JSON programmatically. For the WizBang application, we can define Custom Data to create a customized experience based off the Organization.

custom data


We’ve gone over Stormpath’s prebuilt authorization and how to easily configure groups, permissions, and customer organizations for your Multi-Tenant SaaS. We store and secure all your customer profile data, so you don’t need a user database at all. We also allow you to implement Single Sign-On across your applications by asserting a customer identity across connected applications. And with Stormpath’s hosted ID Site, you don’t have to build any customer login interactions or screens.

ID Site is fully supported in all of our libraries. For more information on how to set up ID Site in your application, check out our docs.

You can watch the full demo how to add multi-tenancy to your application here.

Feel free to drop a line over to email anytime.

Like what you see? to keep up with the latest releases.