Tailoring the Authentication Flow for Amazon Cognito User Pools

Introduction

More Info

Contemporary authentication flows now encompass various challenge types beyond just passwords to verify user identities. These challenges can include CAPTCHAs, dynamic questions, and more. With Amazon Cognito User Pools, you gain a versatile authentication flow that can be tailored to integrate additional methods and facilitate dynamic, server-driven authentication processes. Essentially, we break down the authentication process into two primary steps, executed via two APIs: InitiateAuth and RespondToAuthChallenge. In this sequence, users authenticate by responding to a series of challenges until either authentication fails or they receive their tokens. This structure allows for a fully customizable authentication experience. Additionally, you can enhance your authentication flow using AWS Lambda triggers, which issue and validate their own challenges as part of the process.

In this article, we will delve into the two APIs, detailing their inputs and outputs while demonstrating how to customize your User Pools authentication flow to include additional challenges like CAPTCHAs. For further insights, consider checking out another blog post on this topic here.

New APIs

InitiateAuth

This API initiates the authentication process, clearly communicating to Amazon Cognito how you are attempting to authenticate, along with the initial parameters sent to the pre-authentication Lambda trigger. A successful call results in either tokens (for an authenticated user) or a challenge.

The InitiateAuth API requires the following inputs:

• AuthFlow String
  The name of the authentication flow is defined by the service. Supported options include USER_SRP_AUTH, REFRESH_TOKEN_AUTH, CUSTOM_AUTH, and ADMIN_NO_SRP_AUTH. The USER_SRP_AUTH and REFRESH_TOKEN_AUTH methods were previously accessible through other APIs but are more straightforward with the new ones. For custom flows, use the CUSTOM_AUTH value. More detailed information can be found in the Amazon Cognito Developer Guide under Custom Authentication Flow.
• AuthParameters Map of String, String
  Key/value pairs containing all necessary inputs to initiate the authentication method (e.g., USERNAME=johndoe, SRP_A=AB009809). Missing parameters may lead to authentication failure.
• [ClientMetadata] Map of String, String
  An optional field. Key/value pairs that provide inputs not directly related to authentication but relevant to the pre-authentication Lambda trigger. These can be used for custom validations that determine whether to accept or deny requests based on user context.
• ClientId String
  The app’s client ID for the application attempting authentication.

RespondToAuthChallenge

This API is employed to react to challenges, which may consist of multiple rounds until the user successfully authenticates (and receives tokens) or fails. You have control over the number of challenge rounds based on previously answered challenges. Each call yields either successful authentication (with token issuance), a new challenge, or a failed authentication.

The RespondToAuthChallenge API requires the following inputs:

• ChallengeName String
  The name of the challenge to which the user is responding.
• Session String
  An encrypted session received in the prior step that the client must return unchanged. This session contains state information regarding the current authentication and cannot be replayed; it expires after 3 minutes.
• ChallengeResponses Map of String, String
  Key/value pairs containing all parameters necessary to respond to the challenge (e.g., captchaAnswer=AZ235F).
• ClientId String
  The ClientId attempting authentication.

Outputs of InitiateAuth and RespondToAuthChallenge

A successful call to either API results in tokens signifying the completion of the authentication flow or a challenge accompanied by a session and parameters.

• AuthenticationResult containing Tokens
  If this step concludes the authentication flow, the result will include ID, access, and refresh tokens. For more details, refer to Using Tokens with User Pools in the Amazon Cognito Developer Guide.
• ChallengeName String
  This indicates the name of the next challenge. Possible values include CUSTOM_CHALLENGE for a custom challenge or PASSWORD_VERIFIER for password verification.
• Session String
  An encrypted session received in the previous step, which the client must pass back unchanged.
• ChallengeParameters Map of String, String
  Key/value pairs containing all parameters necessary to prompt the user for the challenge (e.g., captchaUrl=https://xyz.com/captcha/123415).

Exploring Custom Authentication Flow

To provide control over the authentication process, we introduced a CUSTOM_AUTH flow type and offered Lambda triggers that you can use to implement this custom authentication experience. This flow can be segmented into decisions that you customize via Lambda triggers:

• Analyze the challenges the user has answered (both successfully and unsuccessfully) and then either succeed in authentication (and generate tokens), fail authentication, or present a new challenge. This is known as the Define Auth Challenge Lambda trigger.
• Generate a challenge with parameters used to test the user and valid answers for when the challenge is responded to. This is known as the Create Auth Challenge Lambda trigger.
• Validate the answer provided by the user. This is referred to as the Verify Auth Challenge Lambda trigger.

You can enter Lambda triggers as code in the AWS Lambda console. Configuration of Lambda triggers can be done in the Amazon Cognito console on the User Pools Triggers page. The necessary execution rights are automatically created by the console when you select a Lambda trigger.

When an app starts a CUSTOM_AUTH flow, Amazon Cognito executes the Define Auth Challenge Lambda trigger to issue a challenge type. This can either be a standard (built-in) challenge, such as SRP, managed by the Amazon Cognito service, or a custom challenge through a Lambda trigger you provide (CUSTOM_CHALLENGE type). Generally, this process takes as input the past challenges answered by the user and their outcomes. If the challenge is of a custom type, Amazon Cognito will call a Lambda trigger to create and issue the challenge, returning the challenge parameters and valid answers.

Conclusion

Amazon Cognito User Pools facilitate a robust and customizable authentication flow, allowing you to incorporate additional challenge types and validation processes. For more expert insights on this subject, you can visit this resource. Additionally, you may find this article to be an excellent resource for further information on related skills.

Amazon IXD – VGT2 6401 E Howdy Wells Ave, Las Vegas, NV 89115