Using Auth0 to Power Your B2B Multi/Single-Tenant SaaS Solution

EDITOR’S NOTE: Welcome to the EMEA Blog Takeover, where our EMEA employees take over the Auth0 blog to share success stories from the region. This week, you’ll meet our thought leaders across the pond, discover some of our most compelling use cases, and read about the trends that influence how we do business.

TL;DR: In this article, you will learn how Auth0 can support several configurations for single and multi-tenant applications. The setup in Auth0 for multi-tenancy support varies depending on how the multi-tenancy solution is offered to customers, and how much flexibility is required per tenant.

For context, I base the Auth0 configuration in this blog on a fictional product management solution called Product0, which is provided to nearly all of their customers as a multi-tenant SaaS application. Product0 also have some customers who opted for a dedicated instance of the solution, provided as a single-tenant app for each of these customers.

Terminology

First let’s align on some basic terminology. Auth0 is a multi-tenanted solution. A ‘tenant’ is a logical isolation unit, borrowed from the term ‘software multi-tenancy.’ This refers to an architecture where a single instance of the software serves multiple tenants. No tenant can access the instance of another tenant, even though the software might be running on the same machine (hence the logical isolation). For more on tenants, see the Auth0 glossary.

Throughout this article we will refer to a tenant as an ‘Auth0 domain’. An Auth0 domain has a unique name such as “product0.auth0.com” and contains all of the configuration/data for a particular set of applications/use case.

Multi-Tenant = One instance, multiple customers

Single-Tenant = One instance, One customer

"Auth0 is a multi-tenanted solution. A ‘tenant’ is a logical isolation unit, borrowed from the term ‘software multi-tenancy.’"

Tweet This

Auth0’s domain model:

Auth0’s tenanted model of configuration provides a huge amount of flexibility for how Auth0 can be used with a business’s own multi-tenant architecture. Auth0’s domain (tenant) model allows for configurations to be completely isolated from other domains. This means that domains can provide complete separation for users, branding and authentication/authorization policies. Applications configured to use Auth0 for authentication/authorization would only be integrated with a single domain. You could also think of a domain as an “SSO Realm.”

Scenarios

The two scenarios below use the Product0 example and the B2B use case has been kept relatively high level to provide a starting point when looking at how to utilise Auth0 for B2B applications. Connection types will vary depending on how each tenant will authenticate into the application. For the purpose of this article I will talk about database users and enterprise federation using Azure Active Directory.

B2B SaaS Multi-Tenant Application

The most common scenario for B2B SaaS applications is where your B2B SaaS solution is provided to multiple customers as a multi-tenant application. The best way to architect Auth0 to support a multi-tenant application is to use a single Auth0 domain. The multi-tenant application would then be represented in Auth0 as a single application within the “Application” section. This means that the multi-tenant application will only use a single client_id to interact with Auth0.

The diagram below shows the Auth0 architecture to support the Product0 multi-tenant app:

When to use this option:

• A shared multi-tenant app with a single login page (all tenants log in through the same login page, same domain)
• All users across all tenants exist in a single database (Auth0 database connection or custom database connection)
• You wish to use Home Realm Discovery (HRD) for any enterprise connections
• Per customer branding on the login page is not required
• An end user may belong to multiple tenants and therefore need to login to more than one tenant.

Again, Auth0 is a multi-tenant solution, meaning users from different customers all login through the ‘manage.auth0.com’ page, which is Auth0 branded (non-customer specific) and presents all login options to all customers. The Auth0 management dashboard is configured in the same way as the Product0 example above. This setup allows for users to belong to more than one tenant which is a very likely in Auth0.

As this is a multi-tenant app and many customers will be using the same shared instance, it is vital to be able to associate many different connections (methods of authentication) with a single application. This could be a database or one of many different enterprise connections, all of which you can easily configure in Auth0.

In some cases, multi-tenant applications can use a separate URL either as a subdomain or as a path configured for a tenant. For example a multi-tenant application might use URLs in the form of: https://{customer}.product0.com or https://www.product0.com/{customer}. When a user arrives at your application with the vanity URL, you can pick up that tenant value and pass it as the login_hint in the authorize request. The login_hint can then be used drive tenant logic within the universal login page and rules engine. This could also be achieved using the connection parameter if a tenant is only using one connection.

Important: For this scenario, we’d recommend that you only use a single database connection when working with a multi-tenant app configured in Auth0. Although multiple database connections can be configured against a single application, the connectionid is required in order for Auth0 to know which database to authenticate the user against. Auth0 does not attempt authentication against all database connections enabled until it finds the valid user. Using multiple database connections would mean logic would have to be implemented on the login page to determine which connection the user belonged to and set the “connection” parameter as this value before authentication was attempted._

Example login page for the Product0 multi-tenant app with home realm discovery being used for a particular customer.

When working with a multi-tenant app, each organization might use different identity providers (IdPs) such as ADFS, Azure AD, G Suite, or username/password stores. Email domains can be configured against each enterprise connection as a way of routing authentication requests. This is known in Auth0 as home realm discovery (HRD). When a user is authenticating using Auth0 Lock and they enter an email address with a domain which is configured against an enterprise connection, the password field will automatically be disbaled and the email will be associated with the IdP connection. Note that Lock has built-in support for HRD. When building a custom login form, this functionality would need to be implemented.

B2B SaaS Single Tenant

In the case where a single customer has a dedicated instance, single tenant, Auth0 provides the flexibility to manage single tenants within a single Auth0 domain. To support this model effectively, the single tenant will have its own application in Auth0, meaning it has a unique client_id. The assumption here is each single tenant app is hosted on a subdomain for each customer.

The architecture diagram below shows how you can model Auth0 to support the multi-tenant app and each single-tenant instance:

The model above assumes that for the single tenant applications users can only belong to one tenant, each application is mapped to a separate database connection meaning that users of each customer would be logically separated. As password policies and username policies are set per database connection, it is therefore possible to support a different password policy per customer, or be able to use both email and username making this model a great choice if this was a requirement for any of your customers.

"Auth0 provides the flexibility to manage single tenants within a single Auth0 domain."

Tweet This

When to use this option:

• A single-tenant application dedicated to a single customer
• Customer branding on the login page is required
• Only connections configured for the customer should be displayed to the end users of this customer

In the case that a user could belong to more than one single instance tenant or a single instance tenant and a tenant within the multi-tenant instance then a single database connection should be used to store all users.

Let's consider the following requirements you might want to provide for each tenant:

• A customer branded login page
• Show only the associated login options for a customer (i.e. Show login with Azure AD only to the customers configured Azure AD domain)

The branding on the login page can then be driven by the client_id parameter, which is sent from the tenant instance (client/application) to Auth0 in the authorize request.

https://{YOUR_AUTH0_DOMAIN}/authorize?client_id=[...]

The client_id is then available within the universal login page and can be accessed via the config object ‘config.clientID’ to drive branding logic.

Example of a login page with customer specific branding and restricted to only applicable connections (Azure AD) driven by the client_id parameter.

Connections can be enabled/disbaled for each application in the application settings, meaning that only a specific connection(s) relevant to a tenant would be available on the universal login page.

If the connection is known ahead of time (before redirecting to the Auth0 universal login page) or you implement a custom login UI you have full control over the authentication flow. You can choose the connection based on context (like the given email address) or by asking the user, then provide the connection parameter to one of Auth0.js' login methods.

Passing the name of an enterprise connection as the connection parameter in the authorize request will by-pass the Auth0 universal login page and redirect the user to the upstream IdP login page. E.g.

https://{YOUR_AUTH0_DOMAIN}/authorize?client_id=[...]&connection=[...]

This would be recommended when the tenant can be identified (maybe via Vanity URLs or sub domain) and only one connection is applicable.

Key Features in Auth0 to Support B2B SaaS Applications

Enterprise Federation

Many customers today will leverage their own federated directory (IdP) to authenticate into third-party applications. This removes the need for the customer’s end users to manage a separate set of credentials. Auth0 supports several “Enterprise” connections for customers who wish to use their own federated IdP to provide SSO (Single Sign On).

Please see more details on enterprise connections here.

Home Realm Discovery (HRD)

With Auth0 you can offer users multiple methods of authenticating. This is important with SaaS or multi-tenant apps, where many organizations use a single app. Each organization might use different IdPs such as ADFS, Azure AD, G Suite, or username/password stores.

Lock has built in functionality for identity provider selection also known as Home Realm Discovery (HRD). Email domains can be configured against each enterprise connection as a way of routing authentication requests. When a user is authenticating using Auth0 Lock and they enter an email address with a domain which is configured against an enterprise connection, the password field will automatically be disbaled and the email will be associated with the IdP connection.

Please find more information on HRD here.

Delegated administration

It is fairly typical for smaller customers to use database users over enterprise federation, meaning that users for each tenant need to be managed. Usually this would be seen as an administration exercise, which the B2B solution provider would not want to own, and therefore would want to delegate this to the end customer.

Auth0 provides a delegated administration dashboard which exposes the Users tab of the Auth0 dashboard allowing you to easily and securely grant limited access for privileged user accounts. The dashboard exposes a number of hooks allowing you to provide a customized and fine-grained experience.

Alternatively you can build your own delegated administration UI on top of the Auth0 Management API. The Management API exposes endpoints to manage (create/read/edit/delete) user accounts, reset passwords, MFA management and Authorization (manage a user’s role and permissions).

Authorization

Auth0’s Role Based Access Control (RBAC) can provide Authorization capabilities within your B2B applications to control access to content/actions. More details on Authorization capabilities in Auth0 can be found here.

Authentication and Authorization policies per tenant

Auth0’s extensible rules engine allows multi-factor authentication (MFA) challenges to be triggered based on the context of the authentication. As part of the context exposed in rules, both the application (client_id) and the connection are available meaning that MFA can be configured per customer/tenant for both scenarios discussed above in this article.

More information on contextual MFA can be found here.

Using the same context object as mentioned above, rules can be used to drive custom logic per tenant, this could be authorization logic specific to one tenant or as another example, include custom claims in the Access Token/ID Token.

Not covered in this Article

In some B2B use cases, a single Auth0 domain could be used for each tenant/customer. Typically this would be used when each tenant is provided as a fully white labelled instance of the solution, meaning one of more of the following (and not limited to) is required:

• Fully white-labeled customer-specific branding
• Custom domain per customer
• Segregation of user data between tenants
• Isolated authentication policies

Final note

The guidance and examples detailed in this blog were focused on a high level B2B use case for the fictional solution, Product0. For a more detailed in-depth discussion on specific multi-tenancy requirements please contact sales.