Multiple Organization Architecture

There are multiple use cases where users belong to third-party organizations that have signed up for the services you provide. These users may be employees of a third-party organization, customers, or a combination of both. Whatever the situation, this guide will provide you with a high-level overview of common use cases for multi-tenant applications.

B2B applications strive to create a pleasant user experience for the employees and customers of the businesses they serve. To accomplish this, service providers in B2B environments often allow branding to be added to their service for each of the organizations that use it. For example, let’s say you work for AwesomeSaaS (an SaaS software company), and your company uses Human0, an HR application for managing benefits and other HR functions. You access your HR app, and when you log in, the login experience is customized to display the AwesomeSaaS logo and use AwesomeSaaS colors.

As a B2B service provider designing an integration with Auth0, you will need to consider whether or not your customers (i.e., third-party organizations) will allow users from other organizations to log in to their instance of the application, and whether those users should be shared between organizations or isolated to a single organization.

Let’s start by introducing a couple of example applications that will highlight the various use cases. Travel0 is a fictitious company that offers online travel agency services. Travel0 has several applications, but for the purpose of this exercise, we’ll focus on two applications that are marketed directly to organizations:

• Travel0 Corporate Booking: Provides organizations with an online application where their employees can log in to and book work-related travel. Organizations that are customers of this application include:

  • Hoekstra & Associates: A small law office with just a few employees. They do not have an IT department and don’t have the time or capacity to learn how to set up a corporate Identity Provider (IdP).

  • Gupta & Smith Law: A larger law office, but they also do not have an IT department and don’t have the time or capacity to learn how to set up a corporate IdP.

  • MetaHexa Bank: A large finance organization. They provide banking and insurance services and have their own IdP.

  • Many Student University (MSU): A large university with several campuses, where each campus has its own IdP.

• Travel0 Adventure Management: Allows organizations to create and market adventures such as whitewater rafting. Guides (who are freelance, or employees of some third-party travel/event organization) can use this application to create an account and handle scheduling to lead adventures. Organizations that are customers of this application include:

  • AdventureZ: A large tour/event organizer. They have their own IdP that they use for their employees. They rarely need freelancers because they have enough guides on staff, some of whom only work during busy times. They also facilitate their guides’ ability to do freelance work for other companies.

  • Rocky Mountain High Adventures: A new group entering the market for the first time. The cofounders run tours; they reach out to freelancers for help during busy times.

  • Suzie’s Rafting and Ziplines: This company has been around for a long time. They have a staff of guides that handle most of their events, but they also hire freelancers when busy.

Many of the words used in the provided guidance can mean a number of different things. Take a moment to read through each definition so it’s clear when reading through the examples who is fulfilling what role:

• Auth0 Tenant (otherwise known as Authorization Server): Tenant that you create in Auth0. It is an instance of an Authorization Server and represents one or more user domains.

• Auth0 Organizations: Refers to the Auth0 Tenant feature designed to support organizations. An instance of an Auth0 Organization will typically refer to a specific customer of yours.

• Employee: Person who works for your company. They will typically have an account in your Identity Provider (IdP) and may need admin access to one or more Organization Tenant instances. We will only use the term Employee to refer to Employees of your company. For users who belong to your customers' Organizations, see Organization User.

• Identity Provider (IdP): Service, such as Auth0, that manages authentication of users, and optionally, provides user profile information and/or credentials management. The service may also provide delegation of credential validation and profile management via the use of a third-party IdP (such as Azure AD, Google, Facebook, etc.)

• Organization: Third-party company that is one of you customers. You may refer to an organization instance that is created for your application as a tenant; we will refer to it as an Organization Tenant to avoid confusing it with an Auth0 Tenant. 

• Organization Tenant: Refers to a tenant that has been created for your customer as part of your application subscription/provision. This is different from an Auth0 Tenant. 

• Organization User: Person who is logging in to the application as a member of an Organization. This may be an employee (of the Organization) or a customer. Any user referenced in an organization context can be considered an Organization User.

It's important to determine the type of application you provide when it comes to organizational user isolation. There are two fundamental approaches to how and where each of these users are stored: users isolated by organization and users shared between organizations.

The flow diagram above outlines the decision-making process. You should also consider whether administrative-type access is required for an organization instance. This may be for an employee of your organization who acts as an administrator for one or more organizations, or for some other third party that provides help desk services or similar.

The following sections provide detail for each approach to organizational user isolation. Pay close attention to the atypical scenarios associated with each (i.e., where users need access to more than one organization) because these types of use cases often determine which approach more closely aligns with your requirements.

Each organization has its own set of users, and users cannot and should not be able to access other organizations. If they attempt to do so, they should be rejected as unauthorized. If desired, you can force your users to create a separate account for each organization they belong to. As a person, they would be considered to be two or more different users.

In this scenario, a user is tied directly to the organization to which they belong or have access. Users have two options for how they log in: A) they create credentials in identity storage provisioned for the appropriate organization (i.e., UserID/Password Database Connection in your Auth0 Tenant), or B) they log in using their own organization’s IdP. In this use case, it would not make sense for a user to be part of multiple organizations, and the better practice would be to create a separate identity for each organization. Using Travel0 Corporate Booking as an example, the diagram below shows how this would look:

Sally is a typical user: she is an employee of MetaHexa Bank, and she can only access MetaHexa Bank’s instance of Travel0 Corporate Booking.

Pat, on the other hand, is an atypical user. Pat is a freelance paralegal, so she works for both Hoekstra & Associates and Gupta & Smith Law; she will access the Travel0 Corporate Booking instance for each using a separate user identity. One of many advantages for this approach is to limit the possibility of errors by forcing Pat to create two separate personas--one for each law firm. When Pat books travel, she must log in separately to the specific organization instance in order to make the booking.

Pat's situation is likely a rare use case. However, she illustrates what needs to be considered when determining user isolating requirements. If you want to isolate users to the organization with which they’re associated, this requires the creation of separate user identities. In this case, there is one identity for Pat when accessing the Hoekstra & Associates instance of Travel0 Corporate Booking, and a separate one for accessing Gupta & Smith Law’s instance of Travel0 Corporate Booking. 

Applications that have users isolated per organization typically support three different use cases. For the examples in this section, we'll use the Travel0 Corporate Booking application scenarios described in our introduction. Travel0 is the Auth0 customer.

• Organizations that either don’t have their own IdP or don’t know how to use it. These tend to be smaller organizations that don’t have an IT department available to configure Single Sign-On (SSO) with the organization’s Identity Provider (IdP), or else don’t have an organization IdP fit for the task. In our Travel0 Corporate Booking example, Hoekstra & Associates is such an organization.

• Organizations that prefer to configure their own IdP so that their employees don’t have to create a new set of credentials for your application. Most organizations fall into this category. In our Travel0 Corporate Booking example, MetaHexa Bank is such an organization.

• Organizations that require multiple authentication options. Examples of this type of organization include those that frequently acquire new companies, organizations like schools that allow staff and parents to log in to the same application, and organizations that invite partners or customers to log in to their application instance (i.e., B2B2C organizations). In our examples, Many Student University (MSU) would be such an organization.

For the first two types of organizations, the solution tends to be fairly straightforward. These organizations are considered Single IdP organizations, and the approach is almost always the same. To learn more, read Single Identity Provider Organizations.

Organizations that have more than one IdP for the organization trend toward a higher order of intricacy, but there are a few approaches that can minimize complexity. To learn more, read Multiple Identity Provider Organizations.

A user may belong to more than one organization, and it would be convenient if that user did not have to have a separate identity/account as they navigate from one organization to another. Organizations can still use their own IdP in such cases. 

In this scenario, a user is no longer tied directly to the organization to which they belong or have access. Users now have two options for how they log in: A) they create credentials in identity storage provisioned generally (i.e., in a single UserID/Password Database Connection in your Auth0 Tenant), rather than in any identity store specifically allocated in your Auth0 Tenant for the organization, or B) they log in using their own organization’s IdP. Once a user has an identity, they are then given permission to access each of the organizations to which they should have access. This could mean access to just one organization, or it may mean they have access to more than one organization. Users will need to understand that when prompted to log in, they can use the same credentials to access each organization’s instance. Using Travel0 Adventure Management as an example, the diagram above shows how this would look.

Jonno is a typical user. Jonno is an employee of Suzie’s Rafting and Ziplines. Jonno is only able to log in to the instance of Travel0 Adventure Management provisioned to create and guide adventures for Suzie’s Rafting and Ziplines. Jonno’s credentials are either stored in a Database Connection associated with Travel0’s Auth0 Tenant or in Suzie’s Zipline and Rafting’s IdP (depending on whether they want to manage their user identities or not).

Sumana is an atypical user. Sumana is an employee of AdventureZ, but as AdventureZ also coordinates freelance opportunities for the smaller guide companies during high peak times, Sumana has been invited to join Rocky Mountain High Adventures as a freelancer. Sumana is authorized to log in to both AdventureZ and Rocky Mountain’s instances of Travel0 Adventure Management. However, because she has never been invited as a guide to Suzie’s Rafting and Ziplines, she is not authorized to access that instance.

Sumana needs to have the same identity for both organizations because guiding involves the use of a rating system, and Sumana’s ratings need to carry over and be combined between the organizations with which she works. Sumana’s credentials, like Jonno’s, are either stored in a Database Connection associated with Travel0’s Auth0 Tenant, or in AdventureZ’s IdP (depending on whether AdventureZ wants to manage user identities or not). Where her credentials are stored has no bearing on the organization instances to which she has access.

There are scenarios where you will need to provide administrative access across your organizations. Typically, this will be for administrative tasks outside of user Profile/Account management (as described in Profile Management), and you may need to provide access to your employees as well as to third parties.

The Auth0 Dashboard can be configured via role-based access control, which will allow you to define specific roles for your employees across your Auth0 Tenant deployment as a whole. You can even leverage your own corporate IdP to provide Auth0 Tenant Administrator authentication for your employees, as well as extended Tenant Administrator access to trusted third-parties.

For other administrative access, you will typically want to build your own API and/or application, which you will use in conjunction with the Auth0 Management API. Providing administrative access to your Auth0 Tenant via the Auth0 Dashboard for a wide range of users is not recommended. While building such an application/API is beyond the scope of this document, it’s recommended that you seek help from Auth0 Professional Services before embarking on such an endeavor.

• Single Identity Provider Organizations
• Multiple Identity Provider Organizations