Multi-Region replication for user pools
With multi-Region replication (MRR), you can create a replica user pool in an additional AWS Region to provide business continuity and disaster recovery capabilities for your authentication infrastructure. With MRR, registered users can continue to authenticate with your applications even when you lose connectivity to resources in a Region, ensuring your applications remain available.
When you configure MRR, Amazon Cognito creates separate user pools with a shared user pool ID. Each replica user pool hosts authentication services for a shared user directory. The primary user pool serves as the authoritative source for administrative configuration and user directory write operations like password resets and user sign-up. Secondary user pools have can't create users, inherit most settings from the primary user pool, and in a failover state can handle authentication operations like user sign-in and token generation.
Important
Multi-Region replication is not available for all user pools at this time.
Multi-Region replication requires the modern Amazon Cognito infrastructure with enhanced
capabilities and scalability. Some user pools are still on a previous infrastructure and
will be upgraded by AWS to the new infrastructure, which will unlock this feature. In the
Amazon Cognito console, eligible user pools display multi-Region replication configuration options,
and ineligible pools display exception messages. For more information, see Amazon Cognito unlocks advanced capabilities with next-generation
infrastructure
Things to know about multi-Region replication
-
Multi-Region replication has separate add-on costs and requires your user pool to be on the Essentials or Plus feature plan. You can't enable MRR on user pools with the Lite feature plan.
-
You must configure your user pool with a multi-Region customer managed key from AWS KMS before enabling replication. The key must be available in all AWS Regions that have user pool replicas. For more information, see Data encryption.
-
Your user pool must use a multi-Region OIDC issuer to ensure consistent token validation across regions. For more information, see Amazon Cognito user pools as an OIDC issuer.
-
New secondary user pools start in the
INACTIVEstate. Review and configure regional settings before activating the user pool for production use. -
Regional configurations can differ between replicas. You can configure the following settings independently in replicas. All other settings are set in the primary user pool and automatically synchronized to the secondary.
-
Email configuration
-
Email configuration for threat protection notifications
-
SMS configuration
-
Lambda triggers
-
Tags
-
Log export configuration
-
AWS WAF web ACLs
-
-
Data replication between regions may introduce brief delays. The primary user pool syncs settings and user-directory updates to the secondary, and this process is eventually consistent.
Limitations of multi-Region replication
-
You can't generate new users in secondary user pools, either by sign-up or by administrator creation. New federated users can only sign in to a secondary user pool in the failover state if they have previously signed in to the primary user pool.
-
Users can't reset their passwords or modify their profiles in secondary user pools. In a failover state, disable these operations in the user interface and make them available after your health check restores access to the primary user pool.
-
You can have at most one secondary replica in an additional Region per user directory. Any user pool can have a secondary replica.
-
TOTP MFA is not supported in secondary replicas. Users with TOTP MFA configured must authenticate when the user pool in the primary Region is servicing requests.
-
The count of password-based authentication attempts before lockout isn't synchronized across Regions. Each replica maintains its own count of failed authentication attempts.
-
You can only configure automatic failover of multi-Region user pools with a custom domain.
Configuring multi-Region replication
Before you can enable multi-Region replication, ensure your user pool meets the prerequisites: Essentials or Plus feature plan, multi-Region customer managed KMS key, and multi-Region OIDC issuer configuration.
Failover in multi-Region user pools
Failover between two AWS Regions can happen for managed login, federated login, and direct API usage with your user pool. Managed login and federation require a custom domain configured with your primary user pool. You can't configure a different custom domain with replica user pools.
Failover for managed login, federation, and machine-to-machine authorization
Failover is available when your primary user pool has a custom domain. When both user pools have a prefix domain, you can manually test operations on the secondary replica by accessing the secondary prefix domain directly. Custom domains can be served from either the primary or additional replica and Region.
A custom domain is required because it is the endpoint that serves the OAuth 2.0 resources, such as the authorize and token endpoints, and handles the IdP response from third-party federation, including OIDC, SAML, and social providers.
To configure failover, set up a health check in Route 53. You are responsible for what determines the state of this health check. The health check is not directly associated with your DNS CNAME record for your custom domain. However, it is the indicator that determines whether traffic to your custom domain is routed to your primary or replica user pool.
The DNS record for your custom domain can use Route 53 or any third-party DNS provider. Ensure you have a valid CNAME record in your DNS provider pointing to your target alias, which is a CloudFront distribution. You can find the alias target on the Domain page in the Amazon Cognito console.
When the health check is in an unhealthy state, Amazon Cognito serves managed login pages and authentication operations for the custom domain from the secondary replica user pool. When the health check enters a healthy state, Amazon Cognito begins routing traffic back to the primary replica.
Each user pool has its own prefix domain, as these are Region-isolated. You can still directly call these endpoints to handle authentication. However, if federation is configured with third-party IdPs, then there must be two application configurations for each prefix endpoint. As a best practice, use a custom domain to ensure Amazon Cognito handles routing to and from managed login automatically based on the Route 53 health check status.
To update the health check ID in the console
-
Navigate to your user pool in the Amazon Cognito console.
-
Choose Domain under Branding from the menu.
-
Under the Custom domain section, choose the edit option and select Edit multi-Region failover.
-
Toggle the Enable multi-Region failover option.
-
Select your Route 53 health check ID from the available health checks.
-
Choose Save changes.
Failover for Amazon Cognito APIs and SDKs
If you use the Amazon Cognito APIs or SDKs, there's no usage of a custom domain and your application is responsible for routing traffic to the Amazon Cognito service regional endpoint to handle authentication and other API calls.
If you only have an application frontend using a public client, such as a single-page application (SPA) or mobile app, your application needs to be dynamic to route the API calls accordingly. Consider a serverless application backend to help determine which Region authentication with Amazon Cognito should begin against.
If you have an application with a backend, the logic to determine which user pool to authenticate against can be determined here.
If you are using both managed login endpoints and APIs, you can use the same Route 53 health check to be the indicator for your application to decide which Region the API calls to Amazon Cognito should happen against.
