Tenant identity management

Traditional software is usually built to serve a single user at a time. When transformed into a SaaS application, it must support multiple users simultaneously. To achieve this, the system needs to separate users within the application. Tenant identity forms the foundation of that separation.

Tenant identity resides in an identity management system, which is often combined with an access management system. This combination is called a Customer Identity and Access Management (CIAM) service or Identity Provider (IdP). Sometimes, organisations build their own CIAM solutions, but more often they use third-party ones such as Amazon Cognito, Okta, or Keycloak.

To design a tenant identity system that truly aligns with your business, you must first clearly define who the tenant is within your organisation. Different types of tenants come with different requirements, and these distinctions directly shape your application’s architecture. But before diving deeper into tenant identity types, let's look closer at IdPs.

A tenant identity provider is a system or service responsible for managing authentication and tenant identities for SaaS application. It defines tenant lifecycle, identity structure and login methods.

Identity providers act as a trusted intermediary between your customers and your SaaS application, managing authentication, access control, and compliance so you don’t have to reinvent this yourself.

You can implement your tenant identity management system yourself, but the default option is to use purpose-built third-party identity providers to avoid undifferentiated heavy lifting. These solutions come with a range of useful features, such as Multi-Factor Authentication (MFA), and comply with security standards that SaaS providers often need to follow when handling tenants’ data. Now let's look at different tenant identity structures.

The type of tenant identity model where the user is a tenant is most common in B2C SaaS applications. In this model, each user has an isolated account, a personalised experience, and data that belongs exclusively to them. This approach works well for products like productivity apps or streaming services, where the value is delivered directly to individuals rather than organisations.

From a technical standpoint, this means that all your tenants live in the same tenant database, except in cases where your application needs to comply with data residency requirements. In such cases, you may want to have multiple regional tenant databases to keep your customers’ data within specific legal jurisdictions.

A tenant identity structure typically contains fundamental details such as a username, email, and unique identifiers. Beyond that, it often includes tenant-specific metadata, such as roles, subscription tier, feature flags, or entitlements, that define how each tenant experiences the SaaS application. IdPs typically let you specify this metadata and include it in the login response.

In the identity model where you treat your users as tenants, you typically have unified authorisation process for all your tenants and ability to login through the external identity providers such as Google, GitHub, or LinkedIn.

In B2B SaaS applications, tenants are usually entire organisations rather than individual users. This means the identity system needs to support multiple roles and permissions within a single tenant, enabling collaboration while still keeping data securely isolated at the organisational level. Examples include CRM systems, project management tools, or HR platforms, where the value comes from empowering teams and departments to work together efficiently under one company account.

When designing identity model of this type, one of the key architectural decisions is whether to use a shared user pool for all tenants or a dedicated pool per tenant. A shared user pool is easier to manage and maintain since all users across tenants are kept in a single place, simplifying onboarding, updates, and integrations. However, it’s less flexible when it comes to tenant-specific customisations or policies. In contrast, having an identity pool per tenant provides stronger isolation and allows you to tailor authentication flows, user attributes, and security settings to each tenant’s needs, but this approach comes with higher management overhead and complexity.

The tenant identity structure is similar to the previous identity model, with one key addition: a tenantId property, that carries tenant-specific metadata. This property allows the SaaS application to determine and scope user permissions within the correct tenant context.

In SaaS applications where tenants are organisations, it’s common to provide a tenant-specific login experience, and there are several ways to achieve that. One simple option is to include the tenant ID in the URL parameter, such as app.com/login?tenant=123, which makes routing straightforward but looks less polished. A cleaner approach is to use the tenant name as a subdomain, like tenant.app.com/login, which offers a more branded experience while remaining easy to manage. For enterprise-grade setups, some tenants may prefer using their own custom domains, such as tenant.com/login, to fully align the SaaS platform with their corporate identity and deliver a seamless, white-labeled experience for their users.

The third identity model type is one where tenants are still organisations, but users can belong to multiple tenants simultaneously. In this setup, the system must manage complex identity and access scenarios, ensuring that users can seamlessly switch between organisations while maintaining strict data boundaries. This approach is common in collaboration platforms such as Slack or GitHub, where individuals often work with multiple organisations under the same user account.

More commonly, this identity model uses shared user pool for all tenants, where each user’s identity includes a list of assigned tenants within their metadata. This metadata can store not only the tenantId, but also roles and other attributes that define the user’s permissions for each specific tenant.

Now let's look at how the authorisation flow works in dynamic. The process starts when the user tries to access the SaaS application for the first time or when the access token has expired.

When a user accesses the SaaS application without an authorisation token, the application redirects them to the authorisation server, typically a component of the IdP. The AuthServer prompts the user to authenticate and, if successful, issues an access token, for example JWT token, and then redirects the user back to the SaaS application with the token included.

The access token is typically signed and contains the metadata discussed in previous sections. When the SaaS application receives this token, it verifies the signature and, if valid, passes the token to downstream services. These services use the metadata included in the token to scope user permissions and grant entitlements. Since the token usually has a limited lifetime, the user must reauthenticate once it expires.

There are several factors that influence the design of your tenant identity model. These include how tenants are defined, how users are authenticated, what access they have, and how data and compliance are managed across your system. Understanding these factors early on helps you build an identity model that is secure, scalable, and aligned with your business goals. Let’s review the questions that will help you gather the key pieces of information.

How is a tenant defined in your SaaS application?
Understanding how a tenant is defined is crucial because it determines the fundamental boundaries for identity, data, and resource isolation within your SaaS architecture. It affects everything from authentication flows and user management to billing and analytics.

Can users belong to multiple tenants?
Knowing whether users can belong to multiple tenants is essential because it directly impacts how you design authentication, authorisation, and data access models. It influences how user sessions, permissions, and identity mapping are handled across tenant contexts.

What compliance or data residency requirements you must follow?
Understanding compliance and data residency requirements is critical because they dictate where and how tenant identity and user data can be stored and processed. These rules influence your choice of identity providers, encryption standards, and cloud regions.

Do you need to support tiered plans or feature-based pricing?
Knowing whether you need to support tiered plans or feature-based pricing is important because it shapes how you design tenant entitlements and access controls within your SaaS platform. It determines how identity and billing systems interact to enable or restrict features per subscription level.

What authentication methods and features do your customers require?
Knowing which authentication methods and features your customers need is crucial because it shapes both the security and usability of your SaaS application. It guides decisions on supporting standards like SAML, OAuth, or MFA, ensuring seamless integration with customer environments.

Tenant identity management isn’t just a nice-to-have feature, it’s the backbone of your SaaS application. Tenant identity forms the foundation for your tenant isolation, monetisation, and customer-centric experience. Whether you rely on a third-party IdP or build your own CIAM solution, establishing this foundation correctly sets the stage for everything that follows, from smooth authentication flows to seamless customer experience.