Multi-tenant application best practices - Amazon Cognito
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Multi-tenant application best practices

Amazon Cognito user pools operate with multi-tenant applications that generate a volume of requests that must remain within Amazon Cognito quotas. To scale up this capacity when your customer base grows, you can purchase additional quota capacity.


Amazon Cognito quotas are applied per Amazon Web Services account and Amazon Web Services Region. These quotas are shared across all tenants in your application. Review the Amazon Cognito service quotas, and make sure that the quota meets the expected volume and the expected number of tenants in your application.

This section describes methods that you can implement to separate tenants between Amazon Cognito resources within the same Region and Amazon Web Services account. You can also split your tenants across more than one Amazon Web Services account or Region, and give each of them their own quota. Other advantages of multi-Region multi-tenancy include the highest possible level of isolation, shortest network-transit time for globally distributed users, and adherence to existing distribution models in your organization.

Single-Region multi-tenancy can also have advantages for your customers and administrators.

The following list covers some of the advantages of multi-tenancy with shared resources.

Advantages of multi-tenancy
Common user directory

Multi-tenancy supports models where customers have accounts in more than one application. You can link identities from third-party providers into a single consistent user pool profile. In cases where user profiles are unique to their tenant, any multi-tenancy strategy with a single user pool has one point of entry to user administration.

Common security

In a shared user pool, you can create a single standard for security and apply the same advanced security, multi-factor authentication (MFA), and Amazon WAF standards to all tenants. Because an Amazon WAF web ACL must be in the same Amazon Web Services Region as the resource that you associate it with, multi-tenancy offers shared access to a complex resource. When you want to maintain consistent security configuration in multi-Region Amazon Cognito applications, you must apply operational standards that replicate your configuration between resources.

Common customization

You can customize user pools and identity pools with Amazon Lambda. Configuration of Lambda triggers in user pools and Amazon Cognito events in identity pools can become complex. Lambda functions must be in the same Amazon Web Services Region as your user pool or identity pool. Shared Lambda functions can enforce standards for custom authentication flows, user migration, token generation, and other functions within a Region.

Common messaging

Amazon Simple Notification Service (Amazon SNS) requires additional configuration in a Region before you can send SMS messages to your users. You can send email messages with Amazon Simple Email Service (Amazon SES) verified identities and domains that are contained within a Region.

With multi-tenancy, you can share this configuration and maintenance overhead between all of your tenants. Because Amazon SNS and Amazon SES aren't available in all Amazon Web Services Regions, splitting your resources between Regions requires additional consideration.

When you use custom messaging providers, you gain the common customization of a single Lambda function to manage your message delivery.

The hosted UI sets a session cookie in the browser so that it recognizes a user who has already authenticated. When you authenticate local users in a user pool, their session cookie authenticates them for all app clients in the same user pool. A local user exists exclusively in your user pool directory without federation through an external IdP. The session cookie is valid for one hour. You can't change the session cookie duration.

There are two ways to prevent sign-in across app clients with a hosted UI session cookie.

  • Separate your users into per-tenant user pools.

  • Replace hosted UI sign-in with Amazon Cognito user pools API sign-in.