Migrating a user authentication system to Amazon Cognito (or any provider) is a complex process that requires meticulous planning and attention to detail. Throughout our journey, we uncovered critical insights into configuration, best practices, and potential challenges. In this guide, we share the most valuable lessons learnt to help you navigate your Cognito migration smoothly and avoid common pitfalls.

1. Configuration is Key: Get It Right the First Time

Some settings in Amazon Cognito’s user pool configuration are set in stone once selected. This includes critical options like:

• Sign-in Options (e.g., email, phone number)
• Username Case Sensitivity
• Required Attributes (such as phone numbers, email, etc.)

Lesson:

These settings can’t be modified post-creation, so you’ll have to create a new user pool if changes are needed later. This can be disruptive, especially if you’ve already started your migration or have active users.

For example, making a phone number a required attribute may seem harmless—until you encounter partners who can’t provide one. This led to a complete reset of our migration. If you’re uncertain about making an attribute required, consider leaving it optional to maintain flexibility.

2. Mind the Hosted UI Domain Switch

When using Cognito’s Hosted UI, Cognito will assign a default domain, which you can replace with a custom one later. This sounds simple enough, but it’s essential to be aware of how this switch affects user login behaviours. Many users rely on password managers, and any shift in the domain will cause them to lose their saved login autofills, leading to login difficulties and frustrated users.

Cautionary Tale:

A migration was performed without addressing this, resulting in significant login issues. Without observability or tracking in place, the problem wasn’t apparent until trading numbers dropped, causing a scramble to troubleshoot. To avoid this, ensure your new Hosted UI matches your previous login flow’s domain to keep user login habits uninterrupted. Also, ensure you have monitoring and observability in place early so you can catch issues quickly. AWS provides a metric for login success rate so this is a good place to start.

3. The Password Policy Paradox

Cognito offers robust control over password policies, from length to special characters, allowing for a highly secure environment. However, this flexibility can sometimes become a limitation.

Key Points:

• Password Requirements: If you’re migrating users with passwords from a legacy system, know that Cognito’s password policy won’t retroactively enforce stricter requirements. Users with passwords not meeting the new criteria will still be allowed, so setting RESET_REQUIRED on their status might be necessary to prompt a password change.
• Special Character Compatibility: Cognito’s allowed characters don’t include symbols like £, which can be problematic if users in legacy systems used them. During migration, mismatches in allowed characters can lead to login failures, forcing preemptive password changes on your users.

Advice:

To prepare for migration, align your legacy system’s sign-up/registration password policy with the intended Cognito password requirements as early as possible. This ensures that new passwords are migration-ready. Avoid enforcing password requirements during login to prevent access issues. Instead, set up monitoring in your legacy system to detect any passwords containing special characters not supported by Cognito. If a significant percentage of passwords conflict, consider prompting users to update their passwords before migration. Alternatively, you may issue temporary passwords for affected accounts as outlined below.

4. User Migration Strategies: Choosing the Right Path

Migrating users from an existing system into Cognito can follow various strategies, each with its trade-offs:

• Lambda-Based User Migration Trigger: One of the most effective approaches, this trigger allows you to migrate users only when they log in. This method is seamless for active users, while inactive accounts remain untouched, reducing unnecessary migration. You will likely need to keep the trigger active for several months to capture most of the active user base. This method will not check the user's password against your Cognito password policy, so will allow all users to be migrated. As mentioned above, you might want to enforce a password reset for these users.

Be careful with this trigger as the event includes the plaintext password, so we don't want to see any logger.info(event) in this Lambda, or ever for that matter 😉.

• Temporary Passwords for Unmigrated Users: For users who don’t log in during the migration period, consider issuing temporary passwords. This is an effective fallback that ensures no user is left behind, though it requires sending reset instructions and user follow-up.

• Passwordless Authentication Options: To reduce dependency on legacy password compatibility, explore passwordless methods such as one-time codes or magic links. These can simplify the user experience and reduce migration hurdles by minimising password management complexities. We explored this approach thoroughly but ultimately decided against it, as it altered the user experience too much.

5. Addressing Mobile App Complexity and Version Control

Mobile app releases add a unique layer of complexity during migrations, particularly if the app’s authentication flow relies on the legacy system. Unlike web applications, which can deploy updates quickly, mobile app changes depend on users updating their app versions. This makes it essential to plan for backward compatibility.

If you change authentication flows or UI domains, coordinate with mobile release schedules to ensure users on older versions aren’t locked out. Consider keeping the legacy system active until the majority of mobile users have updated, or providing fallback authentication methods for those on previous versions. A smooth transition often requires close collaboration with your mobile development team to minimise user disruption.

6. User Communication and Support Planning

Considering the potential impacts on user behaviour and login experiences, a solid communication strategy can ease the transition for users. You may want to:

• Send emails or in-app notifications ahead of time, informing users of upcoming changes.
• Prepare FAQs or help guides on password resets, updating saved passwords, or handling two-factor authentication.
• Brief your support teams on possible issues and train them to handle potential login and password-reset queries.

Providing clear, proactive communication can minimise user frustration and reduce the volume of support tickets that may arise during the transition.

In Summary

Migrating to Amazon Cognito requires a precise configuration approach and a close understanding of how each setting affects the user experience. The key lessons from our experience are to:

• Set configurations thoughtfully, as they’re often permanent.
• Align Hosted UI domains to maintain password manager compatibility.
• Establish strong but migration-friendly password policies.
• Prepare for mobile complexities by planning around app update cycles.
• Develop a user communication and support strategy to ease the transition.

By applying these insights and setting up vigilant monitoring, you can minimise disruptions and ensure a successful migration to Amazon Cognito.

For a more in-depth guide on Cognito user migration approaches, see this post from The Burning Monk.

For an honest—though perhaps slightly biased—review of Cognito and the migration process, check out this article from FusionAuth.