AWS Partner Network (APN) Blog

Tenant Onboarding Best Practices in SaaS with the AWS Well-Architected SaaS Lens

By Dhammika Sriyananda, Sr. Partner Solutions Architect – AWS

Operational efficiency is a core objective for organizations building multi-tenant software-as-a-service (SaaS) solutions. SaaS businesses rely on automating every aspect of operational experience as a way to avoid supporting any one-off requirements. A big part of this automation story is focused on the tenant onboarding experience, which orchestrates all the steps needed to introduce tenants into a SaaS environment.

The operational excellence pillar of the AWS Well-Architected SaaS Lens provides best practices and guidance around this topic. In this post, I will explore these patterns and discuss their approach and implementation details that could be applied to the tenant onboarding architecture in your own multi-tenant SaaS solution.

Core Onboarding Concepts

With an efficient, automated onboarding mechanism, your solution will be able to provide a robust, repeatable onboarding flow that benefits both customers (tenants) and your SaaS business. Therefore, if you’re building or operating a SaaS solution, it’s important to understand different architectural patterns used to implement an automated tenant onboarding experience.

The key here is to manage core moving parts of the onboarding process via a single mechanism that processes all phases of the onboarding experience. This mechanism orchestrates a series of steps to provision and configure all infrastructure elements needed to support each new tenant.

There are often two distinct entry points into the onboarding process. Some organizations have a self-service experience for tenant onboarding that could be presented via a public landing page. In other cases, operation teams may have an internal process that collects the data/configuration needed for new tenants and onboards them via the SaaS admin portal. Either way, the objective is to serve those requests via the centralized tenant onboarding mechanism.

It’s important to note this onboarding process would need to support different provisioning and configuration strategies. If, for example, you need dedicated (siloed) resources for premium tier tenants, your onboarding process needs to detect the tier of new tenants and initiate the appropriate deployment process to create new resources where necessary. All of your tiering policies that influence provisioning and deployment will be applied by the onboarding process.

In the SaaS Lens, you’ll find recommendations that provide guidance for automating the entire onboarding process. In the sections that follow, I’ll dive deeper into the key aspects of this tenant onboarding experience.

Centralizing Tenant Onboarding Through a SaaS Control Plane

In SaaS environments, we generally separate our architecture into a control and application planes. As a cross-cutting concept, your onboarding services will live within the control plane alongside with the other services that are used to manage and operate your SaaS environment.

The onboarding service will be responsible for orchestrating and applying the policies, strategies, and workflow needed to create a new tenant. This allows the design to evolve and be updated, getting all the benefits that are traditionally associated with a decomposed, autonomous microservice design.

The following diagram illustrates the microservices-based tenant onboarding design with service orchestration that run in the SaaS control plane. It leverages AWS serverless managed services for better scalability, efficiency and optimized cost.SaaS-Lens-Tenant-Onboarding-Flow

Figure 1 – Tenant onboarding steps orchestrated via individual microservices in SaaS control plane.

Let’s go through the main steps illustrated in the diagram that are involved in the tenant onboarding flow:

  1. The Registration microservice handles the tenant onboarding triggers coming from internal and self-service users, being responsible for orchestrating the entire onboarding workflow.
  2. The Tenant management service creates the unique tenant id for the new tenant, and stores the tenant-specific details (tenant id, organization data, tier information, tenant settings and environment details).
  3. The User management service is responsible for creating the tenant admin user in a centralized identity provider (IdP).
    1. Here, I have leveraged Amazon Cognito as the IdP. In this model, I’m creating a separate Cognito user pool for each tenant. Some systems will use a shared construct for all users. This varies based on the requirements of your environment. When the user is created in Cognito, we’ll associate tenant details (tenant id, tier information, API keys) with the user using custom attributes.
    2. The User management service may also create new AWS Identity and Access Management (IAM) roles to specify access control and isolation policies, and attach them to the admin user created above. This allows downstream microservices in the application plane to use these roles/polices to provide authorized resource access.
  4. The tenant provisioning service owns responsibility for creating any tenant-specific infrastructure that might be needed (based on the tenant’s tier). It leverages an infrastructure-as-code (IaC) technology to maintain the automation scripts. During onboarding flow, it uses a CI/CD pipeline to execute these scripts to create infrastructure needed for the new tenant, deploys the relevant microservice artifacts, and performs any additional configuration needed to get the tenant up and running.
  5. The final step here configures the billing experience. Often, this includes integrating with an external billing provider via API calls. This can be built as an asynchronous integration, allowing your onboarding to proceed without waiting for this integration to complete.

Each of the microservices in this onboarding experience should emit tenant-aware logs and metrics during the onboarding flow. This gives your operations team access to analytics and troubleshooting information. It also provides insights about the overall performance and reliability of the onboarding experience.

As a SaaS provider, your objective should be to provide full automation across all the steps described above in the onboarding flow, enabling a frictionless experience that enhances your operational efficiency and agility.

Tier-Based Tenant Provisioning Strategies with Tenant Onboarding

Even though our onboard flow is fully automated for all tenants, the implementation of onboarding can vary per tenant. It may need to support different deployment and configuration strategies for each tenant tier.

As an example, here’s a tiering strategy that could have direct influence on how your onboarding process provisions and configures tenant resources:

  • Basic Tier: A low-cost entry point for tenants that relies heavily on running fully shared infrastructure.
  • Premium Tier: A better performance and service-level agreement (SLA) experience provided for key parts of the system by selectively dedicating some of the system’s storage.
  • Platinum Tier: A fully siloed environment is offered to tenants that have specific isolation, regulatory, or other requirements that lead them to prefer a more dedicated resources.

Here, the different tiers will have a direct impact of provisioning and configuration experience in your onboarding processes. SaaS-Lens-Tenant-Onboarding-Architecture

Figure 2 – Tenant onboarding automation with tier-based dynamic deployment strategy.

The figure above illustrates how the infrastructure provisioning is to be orchestrated to facilitate a dynamic deployment strategy. The following steps describe the flow in details:

  1. The Registration service routes the onboarding requests coming from both internal and self-service users to Tenant provisioning microservice.
  2. For each onboarding request, the Tenant Provisioning service initiates a centralized code pipeline that provides a unified operational experience to build the necessary artifacts needed and to handle the deployment process.
  3. In the deploy phase, the code pipeline will trigger an AWS Lambda function by injecting the job details and parameters needed to execute the deployment.
  4. The Lambda function executes the AWS CloudFormation template passing the necessary details and parameters.
  5. Based on the tier details of the tenant, the CloudFormation stack deploys the appropriate infrastructure resources needed to host the new tenant, facilitating the dynamic deployment strategy.

A detailed implementation of this flow can be found in Serverless SaaS Reference architecture, which contains the code and resources that onboards platinum tenants into dedicated infrastructure with full-stack isolation, while having the rest of the tenants in shared resources. Please find more details in GitHub.

If you plan to monitor the status of the tenant provisioning process, you can add an event tracking component to the CloudFormation flow with Amazon EventBridge. If the process becomes significantly longer, you may think of making the onboarding process asynchronous where you return and provide an acknowledgement to the tenant user after the Tenant Provisioning service has received the onboarding request, and then notify the tenant once the process has been completed.

As a part of the onboarding experience, you’ll want to consider the role it could play in supporting tenant off-boarding as well. It will help to remove any tenant-specific infrastructure resources when the tenants are no longer part of the SaaS product.


In this post, we discussed architectural best practices related to the recommendations in the AWS Well-Architected SaaS Lens framework for providing a frictionless tenant onboarding experience for SaaS solution. It’s important to note the technology, tools, and realities of your SaaS environment will influence the specifics of your onboarding experience.

There is always a series of steps involved in the tenant onboarding flow which need to be properly orchestrated and implemented as a part of the core service in the SaaS control plane to provide the seamless and unified experience to the end user. Based on the type of the SaaS use case, and the technology stack you are using, you can plan the right mechanism to fully automate those steps utilizing best practices.

This centralized process is also essential to supporting the tiering strategies of your application, providing a single place to support the various configuration and deployment models of your system.

Having a fully automated tenant onboarding process is essential to every SaaS environment, enabling organizations to have a repeatable, reliable, and scalable mechanisms for introduce new tenants into your environment.

For more details, refer to the operational excellence pillar section in the SaaS Lens Whitepaper.

Get Started with the Well-Architected SaaS Lens

The AWS Well-Architected SaaS Lens focuses on SaaS workloads and is intended to drive critical thinking for developing and operating SaaS workloads. Each question in the SaaS Lens has a list of best practices, and each best practice has a list of improvement plans to help guide you in implementing them.

The SaaS Lens can be applied to existing workloads or used for new workloads you define in the tool. You can use it to improve the application you are working on, or to get visibility into multiple workloads used by the department or area you are working with.

The SaaS Lens is available in all regions where the AWS Well-Architected Tool is offered, as described in the AWS Regional Services List. There are no costs in using the AWS Well-Architected Tool.

If you’re an AWS customer, find current AWS Partners that can conduct a review by learning about AWS Well-Architected Partners and AWS SaaS Competency Partners.

About AWS SaaS Factory

AWS SaaS Factory helps organizations at any stage of the SaaS journey. Whether looking to build new products, migrate existing applications, or optimize SaaS solutions on AWS, we can help. Visit the AWS SaaS Factory Insights Hub to discover more technical and business content and best practices.

SaaS builders are encouraged to reach out to their account representative to inquire about engagement models and to work with the AWS SaaS Factory team.

Explore today resources for any stage of your SaaS journey from design and build, to launch and optimization.