Amazon Cognito
Developer Guide

Define Auth Challenge Lambda Trigger


                    Challenge Lambda triggers
Define auth challenge

Amazon Cognito invokes this trigger to initiate the custom authentication flow.

The request contains session, which is an array containing all of the challenges that are presented to the user in the authentication process that is underway, along with the corresponding result. The challenge details (ChallengeResult) are stored in chronological order in the session array, with session[0] representing the first challenge that is presented to the user.

The challenge loop will repeat until all challenges are answered.

Define Auth Challenge Lambda Trigger Parameters

These are the parameters required by this Lambda function in addition to the common parameters.

JSON
JSON
{ "request": { "userAttributes": { "string": "string", .... }, "session": [ ChallengeResult, ... ] }, "response": { "challengeName": "string", "issueTokens": boolean, "failAuthentication": boolean }

Define Auth Challenge Request Parameters

userAttributes

One or more name-value pairs representing user attributes.

session

The session element is an array of ChallengeResult elements, each of which contains the following elements:

challengeName

The challenge type. One of: "CUSTOM_CHALLENGE", "PASSWORD_VERIFIER", "SMS_MFA", "DEVICE_SRP_AUTH", "DEVICE_PASSWORD_VERIFIER", or "ADMIN_NO_SRP_AUTH".

challengeResult

Set to true if the user successfully completed the challenge, or false otherwise.

challengeMetaData

Your name for the custom challenge. Used only if challengeName is "CUSTOM_CHALLENGE".

Define Auth Challenge Response Parameters

In the response, you can return the next stage of the authentication process.

challengeName

A string containing the name of the next challenge. If you want to present a new challenge to your user, specify the challenge name here.

issueTokens

Set to true if you determine that the user has sufficiently authenticated by completing the challenges, or false otherwise.

failAuthentication

Set to true if you want to terminate the current authentication process, or false otherwise.

Define Auth Challenge Example

This example defines a series of challenges for authentication and issues tokens only if all of the challenges are successfully completed.

Node.js
Node.js
exports.handler = (event, context, callback) => { if (event.request.session.length == 1 && event.request.session[0].challengeName == 'SRP_A') { event.response.issueTokens = false; event.response.failAuthentication = false; event.response.challengeName = 'PASSWORD_VERIFIER'; } else if (event.request.session.length == 2 && event.request.session[1].challengeName == 'PASSWORD_VERIFIER' && event.request.session[1].challengeResult == true) { event.response.issueTokens = false; event.response.failAuthentication = false; event.response.challengeName = 'CUSTOM_CHALLENGE'; } else if (event.request.session.length == 3 && event.request.session[2].challengeName == 'CUSTOM_CHALLENGE' && event.request.session[2].challengeResult == true) { event.response.issueTokens = true; event.response.failAuthentication = false; } else { event.response.issueTokens = false; event.response.failAuthentication = true; } // Return to Amazon Cognito callback(null, event); }