On this page
Organizations that need to manage a diverse set of user types should consider the Okta multi-tenant solution. This doc provides an overview of the solution, identifies reasons why organizations may want to consider it, and lists the different multi-tenant configurations available.
Important: When implementing a multi-tenant solution, ensure that all tenants are on the same version of Okta, either Okta Classic Engine or Okta Identity Engine. See Identify your Okta solution (opens new window) to determine your tenant's Okta version.
Acme Bank, a fictitious bank, is used throughout this doc to explain the details and key concepts around multi-tenancy. The company came to Okta to centralize and improve their existing identity management infrastructure. To meet the needs and demands of their employees, customers, and partners, they built their solution with a multi-tenant configuration.
A tenant is a single instance of software and supporting infrastructure that supports a group of users. Tenant's can represent any entity that interfaces with the organization such as its employees, customers, or partners. A tenant supports both a business-to-customer (B2C) and business-to-business (B2B) model where users can be either be direct customers or another organization's customers.
A tenant can also be considered as an isolated island of data that is separate and private from other tenants. In the context of identity management, each tenant has its own security policies, user registration settings, user groups, roles, and rules that determine application access. An illustration of these different types of data is shown below:
An organization can create a new tenant for a variety of reasons. For example they may want to:
- Separate user administration and application access for internal employees from outside customers
- Store customer data in a certain region due to regulations and data residency requirements
- Satisfy a unique set of requirements (for example, distinct branding emails, onboarding videos) for a business with their own set of users
- Increase isolation, performance, and scalability for an organization with a large user base
Tenants can comprise one or more of the following entities:
- Individual customers
- A business entity
- External partners
Examples of organizations and their tenants are shown below:
Acme Bank defined their tenants as:
This doc assumes a basic knowledge of the Okta data model and uses Okta terminology such as "org" and "Universal Directory" when describing key concepts and configurations. For more information on these entities and how they relate to each another, see the following resources:
Okta has a highly adaptable and configurable solution for customers looking to implement multi-tenancy. Depending on the solution, a tenant can take the form of an org container, user groups within an org, or a customer-defined entity that is separate from the Okta platform. What form the tenant takes within Okta’s platform is ultimately decided by the customer. Okta offers four main configurations for multi-tenancy. They are:
- Configuration 1: Host tenants in a single org using Universal Directory (UD)
- Configuration 2: Host tenants in separate orgs (for example, hub-and-spoke
- Configuration 3: Mixed. Host tenants in both single and separate orgs
- Configuration 4: Host tenants in a single org not using UD
Host tenants in a single org using Universal Directory (UD)
This configuration hosts all tenants in a single org. Customers have two ways to do this:
- Roll your own custom solution
- Use the okta-dac (opens new window) project
Since a tenant doesn't exist as a separate entity within the org, both methods require abstracting tenants through the use of the org’s users and user groups.
Okta customers should choose this configuration when:
- Cost is the driver.
- Their users use a single version of all applications.
- User self-registration is the same for all users in all tenants.
- All tenants have a relatively small number of password policies (>1000).
- None of their customers and users have data residency requirements.
- All branding communications and onboarding experiences are the same for all users.
- It's acceptable to support unique usernames for each tenant by storing them
in the Okta platform with custom naming conventions (for example,
In this configuration, there's one org for all tenants. For example, Acme Bank configures one org for all of their individual customers, business customers, and partners. Regardless of how this configuration is implemented, tenants are typically created using groups. A group or collection of groups represent the users in a tenant. Groups are assigned to applications that give application access to all users within that group.
Acme Bank offers products, website portals, and other wealth management apps to their customers and partners. The following diagram lays out how these products, users, and groups would be organized within the Okta org.
A recommended strategy is to create user types that allow a hierarchy of users with increasing permissions. As shown in the above diagram, three types of users are defined:
These people are users of the tenant. They can be individual customers in a customer's tenant, customers of a financial technology company, or employees of the Okta customer. Users have the ability to access products and applications assigned to them. Depending on the setup, they can also manage their own profile settings including updating passwords and enrolling in multifactor authentication (MFA).
Admin users manage users of a tenant. Their responsibilities include:
- Adding and updating users within the tenant
- Assigning admin roles to other users
- Configuring Identity Providers
- Verifying email domains
These users can create new tenants and tenant admins. They are used by the Okta customer to manage tenants in their org.
The okta-dac project is one such implementation of this configuration. This project enables multi-tenancy in a single org and is maintained by Okta team members and supported by the developer community. This project (Okta Multi-Tenant Admin) supports the following functionality:
- Multi-tenancy in a single org
- Users can be admins of their own tenants
- Tenant admins can self-configure their own Identity Providers for their tenants
- Tenant admins can manage their own user base
This doc briefly summarizes the Okta Multi-Tenant Admin. For more detailed information on okta-dac as it relates to architecture, setup, and deployment, see the project’s main site (opens new window).
okta-dac consists of the following components:
A container object that stores applications and a tenant’s users and groups
An API that is used by the Delegated Admin Console (DAC) and the Okta End-User dashboard. The Tenants API wraps the Okta API that is used to manage the Okta org’s data.
A tool (DAC) that is used to manage users of a tenant. The tool is split into two UIs that include:
- Super Admin UI: Used to create new tenants and their first admin user. Used by Super Admins.
- Tenant Admin UI: Used to manage users of a specific tenant. Used by the Admin user of a tenant.
A dashboard used to access applications and products
A console is used to manage user authentication settings and application access. Although you can manage users and groups through the Admin Console, it isn't recommended when using okta-dac due to the project's specific naming conventions and unique organizational constraints.
The following diagram illustrates how these components work together:
The DAC, Okta End-User Dashboard, and Admin Console are default UIs provided by Okta. Since these tools use Tenant and Okta APIs to manage the Okta org, Okta customers can plug in their own custom UIs.
The Delegated Admin Console and Okta End-User Dashboard use the Tenant API to convert the org's inherently more flattened layout into abstract concepts such as tenants and products. Concepts such as products and tenants become applications, groups, and users (people) under the physical structure of the org. Following the previous examples, this conversion looks like the following:
Note: okta-dac isn't an official Okta product and doesn't qualify for any support. It's recommended to work with your preferred Okta Solution Provider to integrate this code within your existing portal.
See okta-dac (opens new window) for more information.
Host tenants in separate orgs (for example, hub-and-spoke)
This configuration separates tenants into separate containers (orgs). The most popular architecture for this configuration is known as hub-and-spoke.
Reasons why organizations choose this configuration include:
- Data residency requirements: The data in tenants can more easily be isolated when placed into separate orgs. This isolation becomes relevant when user data is required to reside in a specific region (for example, government regulations).
- Strong delegated admin support: Although there's delegated admin support in okta-dac, the number of delegated responsibilities that are supported is limited. Splitting customers and partners into separate orgs offer the maximum level of delegated responsibility support.
- Out-of-the-box duplicate name support: This configuration offers native support for duplicate usernames, since duplicate usernames can exist in different orgs.
- Branding emails: Branding emails, onboarding videos, and other communications are set at the org level. As a result, this configuration supports unique forms of communications per tenant.
- Performance: For large enterprise customers, there are performance advantages to spreading tenant user authentications into multiple orgs.
- Analytics: Reading analytics and tracking user adoption for each tenant is exponentially easier when tenants are separated into orgs.
- Unique DNSs: Customers in each tenant may want to customize their DNS and "post sign-in" redirect page. In this case, a tenant per org natively supports this functionality.
The Okta supported design for a multi-org, multi-tenant configuration is the hub-and-spoke setup.
The two main components of the hub-and-spoke layout are:
Spoke: Org that contains users, user groups, and applications specific to that tenant. Spokes are responsible for lifecycle management and the authentication of its users.
Hub: Org that contains shared users, user groups, and applications. Spokes access shared applications and platform services through the hub. Hubs provide shared directory services, authentication, sign-in policies, and authorization services to spokes in a centralized way. In addition, hubs can route users to different spokes for authentication access to other spoke’s specific applications.
Using the Org2Org app integration, spokes can add users and give access to shared applications and services through the hub.
Note: The Org2Org app integration isn't available in Okta Developer-Edition orgs, so you can't use a developer org as a spoke org. If you need to test this feature in your Developer-Edition org, contact your Okta account team.
The following diagram illustrates the hub-and-spoke configuration:
To discover more about the hub-and-spoke architecture visit the following links:
- Okta for Global, Distributed Organizations (opens new window)
- An Identity Framework for Higher Education Systems (opens new window)
Hybrid - host tenants in both single and separate orgs
Okta supports a hybrid configuration that mixes the setups described in both the first and second configurations. How this configuration is set up varies from customer to customer. One example of this hybrid configuration lays out orgs in a hub-and-spoke pattern like configuration 2. A spoke on this configuration can be composed of single or multiple tenants. See the following diagram for an illustrated example of this setup:
Depending on the requirements, business customers may require the data isolation, customizations, and other features provided by a single org. Other customers may not have these demands and can be placed on a shared org with other customers. This hybrid configuration supports both types of customers.
Host tenants in a single org not using Universal Directory
In this configuration, the customer assumes responsibility for managing users, groups, and application access outside of the Okta org. Okta’s Universal Directory (UD) isn't used to store the tenants’ users and groups. See the following illustrated example of this configuration:
Additional multi-tenancy resources are below:
- The Secret Features of Okta Access Gateway: Part 1: Multi-data center and multi-tenancy (opens new window)
The Okta identity solution is centered on an org. An org is a private container of data that holds all the resources necessary to manage user authentication. It's composed of three main objects:
- People (Users)
The Okta org is also a place that stores lists of available Identity Providers (IdPs), factors (for MFAs), password policies, and other security-related features.
The following diagram illustrates a simplified view of the Okta org.