Multiple Organization Architecture

There are multiple use case scenarios where users end up belonging to third-party organizations that have signed up for the services you provide. Such users can be employees of some third-party organization, customers, or a combination of both. Whatever the situation, guidance has been created to help you design your integration with Auth0; it should provide you with a high-level overview of the common use cases experienced with respect to multi-tenant applications.

For example, B2B applications strive to create a pleasant user experience for the employees/customers of the businesses they serve. To accomplish this, service providers in B2B environments often allow some 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 would access your HR app at https://awesomesaas.human0.com, and when you log in, the login experience would be 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 one organization in particular.

Let’s start by introducing a couple of examples of applications that will help highlight the various use case scenarios. 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 the 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 (e.g., whitewater rafting, horseback riding, zip line). It allows guides (who are freelance, or employees of some third-party travel/event organization) to sign up for and be scheduled 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 which 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 mostly during busy times.

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

Let’s take a step back for a moment and clarify some terminology. This is important because many of the words used in the provided guidance can be overloaded to mean a number of different things. We’ll be diligent in our use of terms in an attempt to avoid confusion, and we recommend that you take a moment to read through each definition so that 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 is part of 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. Your customers may have users who are in turn employees of their organizations, but we will refer to those individuals using the more general term of Organization Users. We will only use the term Employee to refer to Employees of your company.

• 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 a customer of yours. 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 may be 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.

Now that we’ve covered some terminology, let’s get back to discussing how we might determine the type of application we’re providing when it comes to organizational user isolation. There are essentially two fundamental approaches regarding how/where each of these users can be 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, say, acts as an administrator for one or more organizations, or for some other third party that’s providing help desk services or the like.

In the following sections, we’ll dive into the detail associated with each approach to organizational user isolation. We recommend that you 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 will often help determine which approach more closely maps to 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. Keep in mind that you can force your users to create a separate account for each organization, even if they belong to more than one. As a person, they would be considered to be two 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 even if they were, we would rather they create a separate identity for each. 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. There are many reasons this makes sense, not least for reducing accidental error situations 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 either doesn’t exist for your company or is an example of a rare use case scenario. However, she illustrates the kind of thing that needs to be considered when determining user isolating requirements: if you want users to be isolated to the organization with which they’re associated then you’re making a decision that necessitates 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. 

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 occasions when 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.

From an employee perspective, the Auth0 Dashboard can be configured via role-based access control, which will allow you to define specific roles 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.

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.

• Single Identity Provider Organizations
• Multiple Identity Provider Organizations