Managing Linked Identities in Amazon Cognito

Authentication requirements often evolve as Software-as-a-Service (SaaS) applications grow and mature. A common scenario occurs when your customers initially use your SaaS application with user accounts managed directly in Amazon Cognito, but later want to integrate with their own corporate identity provider, such as Microsoft Entra ID (formerly Azure AD). During this transition, you need to maintain access for existing users while ensuring they use their organization's preferred authentication method. In this post, I'll show you how to use Amazon Cognito's linked identities feature to manage this transition and control which authentication methods are available to your users.

The Challenge

Consider this scenario: You've built a SaaS application that initially manages user authentication through Amazon Cognito user pools with username and password authentication. As your customer base grows, many of your enterprise customers want to use their own identity provider for authentication, following security best practices and simplifying user management.

For example, a customer who has been using your service for a year with 100 users managed in Cognito now wants to integrate with their Microsoft Entra ID instance. They need to:

Maintain their users' access to existing resources and data
Ensure their users authenticate through their corporate identity provider
Prevent the use of original Cognito credentials once the transition is complete

While Cognito's linked identities feature allows you to associate multiple identities with a single user, it doesn't automatically prevent users from using their original Cognito credentials. This is where our solution comes in.

Solution Overview

We'll solve this by:

Linking each customer's existing Cognito user with their corporate identity from their chosen IdP
Implementing a Pre-authentication Lambda trigger to control which authentication methods are allowed
Providing a clear user experience by directing users to their organization's authentication method

Implementation

Step 1: Linking Identities

In a production B2B SaaS environment, you would typically handle identity linking automatically using a Pre Sign-up Lambda trigger. When users sign in through their federated identity provider, the trigger checks for an existing Cognito user (usually matching by email), links the identities if found, or creates a new user if not. This provides a seamless experience as customers transition from native Cognito users to using their federated identity provider.

For this demonstration though, we'll use the AWS CLI to manually link an existing Cognito user with their federated identity:

You can verify the linking was successful by checking the user's attributes:

Step 2: Controlling Authentication Methods

Next, we'll implement a Pre-authentication Lambda trigger that checks the user's status and linked identities to determine whether to allow the authentication attempt. This ensures users authenticate through their organization's identity provider once it's configured:

This Lambda function:

Checks if the authentication attempt is from a native Cognito user
Verifies if the user has linked identities
If the user has a federated identity linked, prevents native Cognito authentication
Provides a clear error message directing users to their organization's login method

Step 3: Configure the Lambda Trigger

After creating the Lambda function, configure it as a Pre-authentication trigger in your Cognito user pool:

Navigate to your user pool in the Amazon Cognito console
Under 'Authentication', find 'Extensions'
Add a Lambda Trigger and set your Lambda function as the 'Pre authentication' trigger

Testing the Solution

To verify the solution works as expected:

A user with linked identities attempting to log in with Cognito credentials will receive the message "Please log in using your organization's sign-in page"
The same user can successfully authenticate through their federated identity provider
Users from organizations that haven't configured federation or users who only exist in Cognito can continue to use their Cognito credentials normally

Conclusion

By implementing this solution, you can effectively support your B2B customers' transition from native Cognito authentication to their preferred identity provider while maintaining a seamless user experience. This approach provides a secure and maintainable way to control authentication methods for your SaaS application's users, while supporting your customers' security and identity management requirements.

Considerations

When implementing this solution, keep in mind:

The Pre-authentication Lambda trigger will run for all authentication attempts. Ensure your logic properly handles both native and federated authentication flows.
Users will need clear communication about the transition from native to federated authentication.
Consider implementing monitoring for failed authentication attempts to help identify any issues during the transition or for anomaly detection.

Resources

Lambda Triggers for Amazon Cognito

SaaS authentication: Identity management with Amazon Cognito user pools

Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.

Site Terms, Privacy, and more.