AWS Documentation » Amazon Cognito » Developer Guide » Amazon Cognito User Pools » Customizing User Pool Workflows with Lambda Triggers » Pre Authentication Lambda Trigger

Pre Authentication Lambda Trigger

Amazon Cognito invokes this trigger when a user attempts to sign in, allowing custom validation to accept or deny the authentication request.

Pre Authentication Lambda Flows

Client Authentication Flow

Server Authentication Flow

The request includes validation data from the client which comes from the ClientMetadata values passed to the user pool InitiateAuth and AdminInitiateAuth API methods.

For more information, see User Pool Authentication Flow.

Pre Authentication Lambda Trigger Parameters

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

JSON

JSON

{
    "request":
        {
            "userAttributes": {
                "string": "string",
                ....
            }
            "validationData": {
                "string": "string",
                "string": "string",
                ....
             }
        },
    "response": {}
}

Pre Authentication Request Parameters

userAttributes

One or more name-value pairs representing user attributes.

validationData

One or more key-value pairs containing the validation data in the user's sign-in request.

Pre Authentication Response Parameters

No additional return information is expected in the response.

Authentication Tutorials

The pre authentication Lambda function is triggered just before Amazon Cognito signs in a new user. See these sign-in tutorials for JavaScript, Android, and iOS.

Platform	Tutorial
JavaScript Identity SDK	Sign in users with JavaScript
Android Identity SDK	Sign in users with Android
iOS Identity SDK	Sign in users with iOS

Pre Authentication Example

This sample function prevents users from a specific user pool app client to sign-in to the user pool.

Node.jsPython

Node.js

exports.handler = (event, context, callback) => {
    if (event.callerContext.clientId === "user-pool-app-client-id-to-be-blocked") {
        var error = new Error("Cannot authenticate users from this user pool app client");

        // Return error to Amazon Cognito
        callback(error, event);
    }

    // Return to Amazon Cognito
    callback(null, event);
};

Python

def lambda_handler(event, context):
    if event['callerContext']['clientId'] == "<user pool app client id to be blocked>":
        raise Exception("Cannot authenticate users from this user pool app client")

    # Return to Amazon Cognito
    return event

Amazon Cognito passes event information to your Lambda function. The function then returns the same event object back to Amazon Cognito, with any changes in the response. In the Lambda console, you can set up a test event with data that’s relevant to your Lambda trigger. The following is a test event for this code sample:

JSON

JSON

{
    "callerContext": {
        "clientId": "<user pool app client id to be blocked>"
    },
    "response": {}
}