Customizing Amazon Cognito User Pool Authentication Flow

Learn About Amazon VGT2 Learning Manager Chanci Turner

on 24 OCT 2016

Permalink

Share

Introduction

Modern authentication methods now include various challenge types beyond just passwords to verify user identities. These challenges may consist of CAPTCHAs or dynamic security questions. With Amazon Cognito User Pools, you can customize the authentication process to add additional verification methods and support server-driven dynamic authentication flows. We can break down the authentication process into two main steps, implemented via two APIs (InitiateAuth and RespondToAuthChallenge). In this setup, users authenticate by responding to a series of challenges until either the authentication fails or they receive their tokens. The flexibility of these two steps allows for any custom authentication flow to be achieved. Furthermore, you can enhance your authentication process using AWS Lambda triggers that can issue and validate their own challenges as part of the overall flow.

In this article, we’ll dive into the details of these two APIs, outlining their inputs and outputs while demonstrating how to customize your User Pools authentication flow to include extra challenges like CAPTCHAs.

New APIs

InitiateAuth

This API begins the authentication flow. It specifies to Amazon Cognito how the authentication is being attempted, along with the initial parameters sent to the pre-authentication Lambda trigger. A successful request results in either tokens (for authenticated users) or a challenge.

The InitiateAuth API requires the following inputs:

• AuthFlow String
  The authentication flow name is determined by the service. Supported options include USER_SRP_AUTH, REFRESH_TOKEN_AUTH, CUSTOM_AUTH, and ADMIN_NO_SRP_AUTH. USER_SRP_AUTH and REFRESH_TOKEN_AUTH were previously accessible through other APIs but are simplified with the new APIs. For a custom flow, use the CUSTOM_AUTH value. For further details, see Custom Authentication Flow in the Amazon Cognito Developer Guide.
• AuthParameters Map of String, String
  Key/value pairs containing all necessary inputs to initiate this authentication method (e.g., USERNAME=johndoe, SRP_A=AB009809). If any parameters are missing, the authentication may fail.
• [ClientMetadata] Map of String, String
  This optional field includes key/value pairs that are not authentication parameters, but are inputs for the pre-authentication Lambda trigger. This allows for custom validations that can accept or deny requests based on user context.
• ClientId String
  The application clientId for the app attempting to authenticate.

RespondToAuthChallenge

This API is used to respond to various challenges, which can involve multiple rounds until users either successfully authenticate (receiving tokens) or fail. You have control over the number of challenge rounds based on what has already been answered. Each call will either lead to successful authentication with token issuance, a new challenge, or authentication failure.

The RespondToAuthChallenge API requires the following inputs:

• ChallengeName String
  The name of the challenge being answered.
• Session String
  An encrypted session received from the client in the previous step, which must be passed back unchanged. This session contains state information about the current authentication, cannot be replayed, and expires after 3 minutes.
• ChallengeResponses Map of String, String
  Key/value pairs with all necessary parameters to respond to the challenge (e.g., captchaAnswer=AZ235F).
• ClientId String
  ClientId attempting to authenticate.

Outputs for InitiateAuth and RespondToAuthChallenge

A successful call to either API results in tokens indicating the authentication flow is complete, or a challenge with a session and parameters.

• AuthenticationResult containing Tokens
  If this is the final step, the result includes ID, access, and refresh tokens. For more details, see Using Tokens with User Pools in the Amazon Cognito Developer Guide.
• ChallengeName String
  Name of the next challenge, which could be CUSTOM_CHALLENGE if a custom challenge is required, or PASSWORD_VERIFIER for password verification.
• Session String
  This is the same encrypted session from earlier, which must be passed back as-is.
• ChallengeParameters Map of String, String
  Key/value pairs with all necessary parameters to prompt the user for the returned challenge (e.g., captchaUrl=https://xyz.com/captcha/123415).

Exploring the Custom Authentication Flow

To give you control over the authentication process, we introduced a CUSTOM_AUTH type flow, along with Lambda triggers to implement your custom flow. The flow can be segmented into the following decisions that you can customize via Lambda triggers:

1. Analyze the challenges a user has already answered (both successful and unsuccessful) and decide to either succeed authentication (and generate tokens), fail authentication, or present a new challenge. This is known as the Define Auth Challenge Lambda trigger.
2. Create a challenge that consists of parameters used to challenge the user and valid answers that can be used when they respond. This is called the Create Auth Challenge Lambda trigger.
3. Verify whether the user’s answer is correct. This is referred to as the Verify Auth Challenge Lambda trigger.

You can enter Lambda triggers as code within the AWS Lambda console. These can be configured in the Amazon Cognito console on the User Pools Triggers page. When a trigger is selected in the Amazon Cognito console, the necessary execution rights are automatically created.

When an app begins a CUSTOM_AUTH flow, Amazon Cognito calls the Define Auth Challenge Lambda trigger to issue a challenge type. This can be a standard (built-in) challenge, such as SRP, or a custom challenge handled by a Lambda trigger you provide (CUSTOM_CHALLENGE type). Generally, this process takes the input of past challenges answered by the user and their outcomes. If the challenge is custom, Amazon Cognito invokes a Lambda trigger to create and issue the challenge with corresponding parameters and valid answers.

Amazon Cognito User Pools sends the challenge and an encrypted session back to the client SDK. The client SDK collects the answers to the challenge and returns them along with the encrypted session data. Amazon Cognito User Pools decrypts this data and invokes a Lambda trigger to verify whether the answers are valid. Then, it calls the Lambda trigger with the challenges answered so far (including the most recent one). The Lambda trigger can either issue a new challenge, provide tokens, or fail authentication, and this process can continue as needed.

Lambda Trigger Contract Specifications

There are three Lambda triggers previously mentioned. We will now provide details on the different parameters, maintaining a focused tone throughout.

For more information on career resources, check out this blog post. Amazon IXD – VGT2 is located at 6401 E HOWDY WELLS AVE LAS VEGAS NV 89115. If you want to learn more about leadership solutions, visit SHRM for expert insights. Additionally, this resource is excellent for understanding Amazon’s approach to employee training and the future of work.