Amazon Cognito & Corbado Connect Passkey Integration

Try our demo application to see how Corbado Connect integrates passkeys into your application.

Introduction

Corbado Connect allows you to seamlessly integrate passkey-first authentication into your existing Amazon Cognito user pools. This enables you to offer your users a secure and convenient login experience without passwords, while still leveraging the power of Cognito for user management.

This guide will walk you through the process of integrating Corbado Connect with Amazon Cognito, using a sample Next.js application to demonstrate the key concepts.

Amazon Cognito is a service that provides authentication, authorization, and user management for your web and mobile apps. You can learn more about it on the official Amazon Cognito website.

How it Works

The integration between Corbado Connect and Amazon Cognito leverages a powerful feature known as a Custom Authentication Flow. This feature allows developers to create their own challenge-and-response models using AWS Lambda functions, which is ideal for integrating external authentication mechanisms like Corbado’s passkey-first solution.

Instead of a traditional username and password, we will define a custom flow that uses a passkey signature as the challenge.

To implement this, we need to configure the Cognito User Pool to use three specific AWS Lambda triggers:

define_auth_challenge: This Lambda acts as the orchestrator of our custom flow. It determines which challenge to present to the user at each step of the authentication process.
create_auth_challenge: This Lambda is responsible for creating the challenge itself. In our case, it won’t be creating a secret, but rather preparing for the verification that happens in the next step.
verify_auth_challenge_response: This is where the core verification logic resides. This Lambda takes the signed passkey data from the frontend (provided by Corbado Connect), and verifies it against Corbado’s Backend API to confirm the user’s identity. If verification is successful, it informs Cognito to issue the session tokens.

Later in this guide, we will dive deep into the source code and configuration of each of these functions.

Example Application

To best illustrate the integration, we will refer to a complete example application. This application is built with the following technologies:

Next.js: A popular React framework for building server-rendered applications.
AWS Amplify: A library that simplifies interacting with AWS services like Cognito from a frontend application.

We will guide you through the implementation of two primary user flows: sign-up and login.

In our example application, the initial user sign-up is handled through a conventional method (e.g., email and password) managed by Amazon Cognito. Once the user has an account and is logged in, we offer them the option to add a passkey to their account for future passwordless logins. This process is often called “passkey append”.

The complete flow is illustrated in detail here.

Implementation Overview

The user sign-up process consists of a series of interactions between the example application (utilizing AWS Amplify), Amazon Cognito, and Corbado APIs. These interactions are best illustrated using a sequence diagram:

In the following sections, we will explain each step in detail.

UI Component Integration

We start by integrating the CorbadoConnectAppend component from the @corbado/connect-react library. The component takes care of the entire UI and logic for creating and storing the passkey.

Here’s how it’s used in our example application’s post-login page:

/application/cognito/app/(auth-required)/post-login/page.tsx

'use client';

import {CorbadoConnectAppend} from "@corbado/connect-react";
import {useRouter} from "next/navigation";
import {getCorbadoConnectTokenAppend, postPasskeyAppend} from "@/app/(auth-required)/post-login/actions";
import {fetchAuthSession} from "aws-amplify/auth";
import {AppendStatus} from "@corbado/types";

export default function Page() {
    const router = useRouter();

    return (
        <div className="flex h-screen w-screen items-center justify-center bg-gray-50">
            <div className="z-10 w-full max-w-sm overflow-hidden rounded-2xl border border-gray-100 shadow-xl">
                <div className="flex flex-col space-y-4 bg-gray-50 px-4 py-8 sm:px-8">
                    <CorbadoConnectAppend
                        onSkip={async () => router.push('/profile')}
                        appendTokenProvider={async () => {
                            const session = await fetchAuthSession();
                            const idToken = session.tokens?.idToken?.toString();

                            return await getCorbadoConnectTokenAppend(idToken);
                        }}
                        onComplete={async (appendStatus: AppendStatus, clientState: string) => {
                            await postPasskeyAppend(appendStatus, clientState);
                            router.push('/profile');
                        }}
                    />
                </div>
            </div>
        </div>
    );
}

For a detailed explanation of all available props for this component, please see the CorbadoConnectAppend component documentation.

Obtaining the ConnectToken

When the component is initialized, it executes the function given in appendTokenProvider to request a short-lived ConnectToken from Corbado’s Backend API (this token authorizes the creation of a passkey for a specific and authenticated user, see ConnectToken documentation for more details).

The frontend first needs to get the idToken for the currently logged-in user from AWS Amplify. This JWT is proof of the user’s session with Amazon Cognito. The idToken is then sent to a Next.js Server Action:

appendTokenProvider={async () => {
    const session = await fetchAuthSession();
    const idToken = session.tokens?.idToken?.toString();

    return await getCorbadoConnectTokenAppend(idToken);
}}

The server action first verifies the idToken to ensure it’s valid and extracts the user’s identity, then requests the ConnectToken by calling the utility function getCorbadoConnectToken():

/application/cognito/app/(auth-required)/post-login/actions.ts

'use server';

import {getCorbadoConnectToken, verifyAmplifyToken} from "@/lib/utils";

export async function getCorbadoConnectTokenAppend(idToken?: string) {
    if (!idToken) {
        throw new Error('idToken is required');
    }

    const {displayName, identifier} = await verifyAmplifyToken(idToken);

    return getCorbadoConnectToken('passkey-append', displayName, identifier);
}

The utility function subsequently manages the request to the Corbado Backend API:

export const getCorbadoConnectToken = async (connectTokenType: string, displayName: string, identifier: string): Promise<string> => {
    const payload = {
        type: connectTokenType,
        data: {
            displayName: displayName,
            identifier: identifier,
        },
    };

    const body = JSON.stringify(payload);

    const url = `${process.env.CORBADO_BACKEND_API_URL}/v2/connectTokens`;
    const response = await fetch(url, {
        method: 'POST',
        headers: {
            Authorization: `Basic ${process.env.CORBADO_BACKEND_API_BASIC_AUTH}`,
            'Content-Type': 'application/json',
        },
        cache: 'no-cache',
        body: body,
    });

    const out = await response.json();

    return out.secret;
}

Updating MFA Settings

After a passkey is created, it’s necessary to update the MFA settings in Amazon Cognito. This can be achieved using Corbado actions, which enable you to extensively customize Corbado Connect to suit your specific requirements.

The post-append action utilizes the AdminGetUser command from Amazon Cognito to verify if MFA is already configured. If it is not, the AdminSetUserMFAPreference command is executed to update the settings:

index.mjs

import { AdminGetUserCommand, AdminSetUserMFAPreferenceCommand, CognitoIdentityProviderClient } from '@aws-sdk/client-cognito-identity-provider';
import { STSClient, AssumeRoleCommand } from "@aws-sdk/client-sts";

// ID of Cognito user pool
const userPoolId = process.env.USER_POOL_ID;

// ARN of role to assume
const roleArn = process.env.ASSUME_ROLE_ARN;

let cognitoClientCache = null;
let credentialsExpiryTime = null;

const assumeRole = async () => {
    const command = new AssumeRoleCommand({
        RoleArn: roleArn,
        RoleSessionName: 'LambdaSession',
        DurationSeconds: 3600
    });

    const client = new STSClient();
    const response = await client.send(command);
    const { AccessKeyId, SecretAccessKey, SessionToken, Expiration } = response.Credentials;
    credentialsExpiryTime = new Date(Expiration).getTime();

    return new CognitoIdentityProviderClient({
        credentials: {
            accessKeyId: AccessKeyId,
            secretAccessKey: SecretAccessKey,
            sessionToken: SessionToken,
        }
    });
};

const getCognitoClient = async () => {
    const currentTime = Date.now();

    if (!cognitoClientCache || !credentialsExpiryTime || currentTime >= credentialsExpiryTime) {
        cognitoClientCache = await assumeRole();
    }

    return cognitoClientCache;
};

// Main handler function
export const handler = async (event) => {
    console.log('Received event:', event);

    try {
        const cognitoClient = await getCognitoClient();
        const username = event.username;

        // Get user and check MFA settings
        const getUserCommand = new AdminGetUserCommand({
            UserPoolId: userPoolId,
            Username: username,
        });

        const user = await cognitoClient.send(getUserCommand);
        if (user.UserMFASettingList && user.UserMFASettingList.length > 0) {
            console.log('User has MFA settings already set', user.UserMFASettingList);

            return {
                statusCode: 200,
                body: {},
            };
        }

        // Set MFA preference because not done yet (see above)
        const command = new AdminSetUserMFAPreferenceCommand({
            UserPoolId: userPoolId,
            Username: username,
            SMSMfaSettings: {
                Enabled: true,
                PreferredMfa: true,
            }
        });

        await cognitoClient.send(command);

        return {
            statusCode: 200,
            body: {}
        };
    } catch (error) {
        console.error('Caught exception:', error);

        return {
            statusCode: 500,
            body: JSON.stringify({
                message: 'Caught exception',
                error: error.message,
            }),
        };
    }
};

Now that users can associate passkeys with their accounts, we can enable a truly passwordless login experience. This is where the Amazon Cognito custom authentication flow we outlined in the “How it Works” section becomes essential.

The goal is to authenticate a user with their passkey using Corbado Connect and, upon success, establish an authenticated session with Amazon Cognito. To achieve this, we will use our three custom AWS Lambda functions to bridge the gap between the two systems and ultimately receive valid session tokens from Amazon Cognito.

The complete flow is illustrated in detail here.

Implementation Overview

The user login process consists of a series of interactions between the example application (utilizing AWS Amplify), Amazon Cognito, Lambda functions, and Corbado APIs. These interactions are best illustrated using a sequence diagram:

The signedPasskeyData is a short-lived, single-use JSON Web Token (JWT) that proves a successful passkey authentication with Corbado. It is the key artifact that connects the two systems.

In the following sections, we will explain each step in detail.

UI Component Integration

Again, we start by integrating the CorbadoConnectLogin component from the @corbado/connect-react library. The component takes care of the entire UI and logic for handling the passkey login and passing the result to our application logic to complete the login with Amazon Cognito.

The core logic resides in a client component that wraps the CorbadoConnectLogin component:

/application/cognito/app/login/WrappedLogin.tsx

'use client';

import {useRouter} from "next/navigation";
import useDevBox from "@/components/useDevBox";
import React, {useState} from "react";
import {confirmSignIn, signIn} from "aws-amplify/auth";
import ConventionalLogin from "@/app/login/ConventionalLogin";
import {CorbadoConnectLogin} from "@corbado/connect-react";
import Link from "next/link";
import {postPasskeyLogin} from "@/app/login/actions";

export type Props = {
    clientState: string | undefined;
};

const decodeJwt = (token: string) => {
    const [, payload] = token.split('.');
    return JSON.parse(atob(payload));
}

type WithWebauthnId = {
    webauthnId: string;
}

const WrappedLogin = ({clientState}: Props) => {
    const router = useRouter();
    const {integratePasskeys} = useDevBox();

    const [conventionalLoginVisible, setConventionalLoginVisible] = useState(false);
    const [email, setEmail] = useState('');
    const [fallbackErrorMessage, setFallbackErrorMessage] = useState('');

    console.log('fallbackErrorMessage', fallbackErrorMessage);

    const postPasskeyLoginNew = async (signedPasskeyData: string, clientState: string) => {

        // decode JWT
        const decoded = decodeJwt(signedPasskeyData) as WithWebauthnId;

        try {
            await signIn({
                username: decoded.webauthnId,
                options: {authFlowType: 'CUSTOM_WITHOUT_SRP'}
            });

            const resultConfirm = await confirmSignIn({
                challengeResponse: signedPasskeyData,
            });
            console.log('resultConfirm', resultConfirm);

            await postPasskeyLogin(clientState);

            if (integratePasskeys) {
                await router.push('/post-login');
            } else {
                await router.push('/profile');
            }
        } catch (e) {
            console.error(e);
        }
    }

    return (
        <div className="flex h-screen w-screen items-center justify-center bg-gray-50">
            <div className="z-10 w-full max-w-sm overflow-hidden rounded-2xl border border-gray-100 shadow-xl m-4">
                {!integratePasskeys || conventionalLoginVisible ? (
                    <ConventionalLogin integratePasskeys={integratePasskeys}
                                       initialUserProvidedIdentifier={email}/>
                ) : null}
                {integratePasskeys && !conventionalLoginVisible ? (
                    <>
                        <div
                            className="flex flex-col items-center justify-center space-y-3 border-b border-gray-200 bg-white px-4 py-6 pt-8 text-center sm:px-8">
                            <h3 className="text-xl font-semibold">Login with passkeys</h3>
                            <p className="text-sm text-gray-500">
                                A simple and secure way to log in.
                            </p>
                        </div>
                        <div className='login-area bg-gray-50 px-4 py-8 sm:px-8 justify-center'>
                            <CorbadoConnectLogin
                                onFallback={(identifier: string, message: string) => {
                                    setEmail(identifier);
                                    setConventionalLoginVisible(true);
                                    setFallbackErrorMessage(message);
                                }}
                                onFallbackCustom={(identifier: string, code: string) => {
                                    setEmail(identifier);
                                    setConventionalLoginVisible(true);
                                    setFallbackErrorMessage(code);
                                }}
                                onError={(error: string) => console.log('error', error)}
                                onLoaded={(msg: string) => console.log('component has loaded: ' + msg)}
                                onComplete={async (signedPasskeyData: string, newClientState: string) => {
                                    await postPasskeyLoginNew(signedPasskeyData, newClientState);
                                }}
                                onSignupClick={() => router.push('/signup')}
                                clientState={clientState}
                            />
                        </div>
                    </>
                ) : null}
                <p className="text-center text-sm text-gray-600 mb-10">
                    {"Don't have an account? "}
                    <Link href="/signup" className="font-semibold text-gray-800">
                        Sign up
                    </Link>
                    {' for free.'}
                </p>
            </div>
        </div>
    );
}

export default WrappedLogin;

For a detailed explanation of all available props for this component, please see the CorbadoConnectLogin component documentation.

The onComplete handler triggers our postPasskeyLoginNew function, which performs the final steps to log the user into Cognito:

Decode the JWT: The signedPasskeyData is a JWT. We decode it to extract the webauthnId, which is a stable identifier for the user in Corbado’s system. We will use this as the username for Amazon Cognito’s custom flow.
signIn: We call signIn from the AWS Amplify library, passing the webauthnId as the username and specifying authFlowType: 'CUSTOM_WITHOUT_SRP'. This initiates the custom authentication flow and triggers our define_auth_challenge and create_auth_challenge Lambdas.
confirmSignIn: We then immediately call confirmSignIn, providing the entire signedPasskeyData as the challengeResponse. This is the answer to the custom challenge, which triggers our verify_auth_challenge_response Lambda.
Redirection: Once confirmSignIn completes successfully, Amazon Cognito has issued valid session tokens to the Amplify library. The user is now fully authenticated, and we can redirect them to a protected page, like their profile.

Identifier Translation

Since Corbado Connect only stores the Amazon Cognito username and not the user’s email address, we need to translate between these identifiers during login. This translation is handled through Corbado actions, which provide extensive customization capabilities for Corbado Connect to meet your specific requirements.

The pre-login action utilizes the AdminGetUser command from Amazon Cognito to search for a user by their email address and return the corresponding Amazon Cognito username to Corbado Connect:

index.mjs

import { AdminGetUserCommand, CognitoIdentityProviderClient, ListUsersCommand } from '@aws-sdk/client-cognito-identity-provider';
import { STSClient, AssumeRoleCommand } from "@aws-sdk/client-sts";

// ID of Cognito user pool
const userPoolId = process.env.USER_POOL_ID;

// ARN of role to assume 
const roleArn = process.env.ASSUME_ROLE_ARN;

let cognitoClientCache = null;
let credentialsExpiryTime = null;

const errorUserNotFound = () => {
    console.log('Returned error with code "user_not_found"');

    return {
        statusCode: 200,
        body: {
            identifier: '',
            error: {
                return: true,
                code: 'user_not_found',
                message: 'There is no account registered to that email address.',
            },
        },
    };
};

const errorUntyped = (message) => {
    console.log(`Returned error code "untyped" and message "${message}"`);

    return {
        statusCode: 200,
        body: {
            identifier: '',
            error: {
                return: true,
                code: 'untyped',
                message
            },
        },
    };
}

const errorCustom = (code, payload) => {
    console.log(`Returned error code "${code}" and payload "${payload}"`);

    return {
        statusCode: 200,
        body: {
            identifier: '',
            error: {
                return: true,
                code,
                payload,
            },
        },
    };
}

const success = (identifier) => {
    console.log(`Returned success with identifier "${identifier}"`);

    return {
        statusCode: 200,
        body: {
            identifier,
        },
    };
}

const errorSilent = (code) => {
    console.log(`Returned error with code "${code}"`);

    return {
        statusCode: 200,
        body: {
            identifier: '',
            error: {
                return: false,
                code,
            },
        },
    };
}

const assumeRole = async () => {
    const command = new AssumeRoleCommand({
        RoleArn: roleArn,
        RoleSessionName: 'LambdaSession',
        DurationSeconds: 3600
    });

    const client = new STSClient();
    const response = await client.send(command);
    const { AccessKeyId, SecretAccessKey, SessionToken, Expiration } = response.Credentials;
    credentialsExpiryTime = new Date(Expiration).getTime();

    return new CognitoIdentityProviderClient({
        credentials: {
            accessKeyId: AccessKeyId,
            secretAccessKey: SecretAccessKey,
            sessionToken: SessionToken,
        }
    });
};

const getCognitoClient = async () => {
    const currentTime = Date.now();

    if (!cognitoClientCache || !credentialsExpiryTime || currentTime >= credentialsExpiryTime) {
        cognitoClientCache = await assumeRole();
    }

    return cognitoClientCache;
};

const handleUserNotFoundException = async (userPoolId, identifier) => {
    console.log('Falling back to search by email...');

    // users that have not confirmed their email will not be found by 
    // the AdminGetUserCommand => we need to search by email using the ListUsersCommand
    const listUsersCommand = new ListUsersCommand({
        UserPoolId: userPoolId,
        Filter: `email = "${identifier}"`,
    });

    const listUsersData = await cognitoClientCache.send(listUsersCommand);
    if (listUsersData.Users.length > 0) {
        const user = listUsersData.Users[0];
        if (user.UserStatus === 'FORCE_CHANGE_PASSWORD') {
            return errorSilent('force_change_password');
        } else {
            return errorUntyped('unhandled user status');
        }
    }

    return errorUserNotFound();
};

// Main handler function
export const handler = async (event) => {
    console.log('Received event:', event);

    try {
        const cognitoClient = await getCognitoClient();

        // The given identifier (in our Cognito demo this is an email address)
        const identifier = event.identifier;
        
        const getUserCommand = new AdminGetUserCommand({
            UserPoolId: userPoolId,
            Username: identifier,
        });

        const data = await cognitoClient.send(getUserCommand);
        
        const userStatus = data.UserStatus;
        const userEnabled = data.Enabled;

        // The Cognito username (e.g. 83942812-f091-7083-8632-7b8052ece3e5) that
        // will get returned in success case (see below). The Cognito username will 
        // be set by Cognito because we only configured "email" as sign-in identifier
        // at the Cognito user pool.
        const foreignID = data.Username;

        if (userStatus === 'CONFIRMED' && userEnabled) {
            return success(foreignID);
        } else if (userStatus === 'CONFIRMED' && !userEnabled) {
            // account has been deactivated or locked
            return errorSilent('account_disabled');
        } else if (userStatus === 'FORCE_CHANGE_PASSWORD') {
            return errorSilent('force_change_password');
        } else if (userStatus === 'RESET_REQUIRED') {
            return errorCustom('reset_required', '');
        } else {
            return errorUntyped('unhandled user status');
        }
    } catch (error) {
        console.error('Caught exception:', error);

        if (error.name === 'UserNotFoundException') {
            return await handleUserNotFoundException(userPoolId, identifier);
        }

        return errorUntyped(error.message);
    }
};

Custom Lambda functions

As introduced in the “How it Works” section, the integration between Corbado Connect and Amazon Cognito relies on three custom Lambda functions to handle the authentication flow.

These functions work together to verify passkey authentications and manage the challenge-response cycle in Amazon Cognito. Let’s dive deeper into each function’s implementation and configuration.

Secrets

Our custom Lambda functions need to communicate securely with Corbado’s Backend API. To do this, they require access to sensitive credentials, namely your Project ID and API Secret.

It is critical to never hard-code secrets directly into your Lambda function’s source code. Instead, you should use a dedicated service for managing secrets. For our example application, and as a recommended best practice, we use AWS Systems Manager (SSM) Parameter Store.

By storing credentials as SecureString parameters in the SSM Parameter Store, you ensure that they are encrypted at rest. You can then grant the Lambda function’s IAM role the necessary permissions to read these specific parameters at runtime. This approach provides a secure and scalable way to manage your secrets, separating them from your application code.

Implementation

Here we will examine the code for each of the three Lambda functions required for the custom authentication flow.

This is the first and last Lambda to be called in the flow. It acts as the orchestrator or state machine.

index.mjs

// This is the 1st lambda function in the Cognito custom auth flow
export const handler = async(event) => {
  console.log('Received event:', event);

  if (!event.request.session.length) {
    // The auth flow just started, send a custom challenge
    return customChallenge(event);
  }

  const lastResponse = event.request.session.slice(-1)[0];
  if (lastResponse.challengeResult === true) {
    return allow(event);
  } else if (countAttempts(event, false) === 0) {
    return customChallenge(event);
  }

  return customChallenge(event)
};

function allow(event) {
  console.log("Authentication allowed!");

  event.response.issueTokens = true;
  event.response.failAuthentication = false;

  return event;
}

function customChallenge(event) {
  event.response.issueTokens = false;
  event.response.failAuthentication = false;
  event.response.challengeName = "CUSTOM_CHALLENGE";

  return event;
}

function countAttempts(event, excludeProvideAuthParameters = true) {
  if (!excludeProvideAuthParameters) {
    return event.request.session.length;
  }

  return event.request.session.filter(
    (entry) => entry.challengeMetadata !== "PROVIDE_AUTH_PARAMETERS"
  ).length;
}

This is the first and last Lambda to be called in the flow. It acts as the orchestrator or state machine.

index.mjs

// This is the 1st lambda function in the Cognito custom auth flow
export const handler = async(event) => {
  console.log('Received event:', event);

  if (!event.request.session.length) {
    // The auth flow just started, send a custom challenge
    return customChallenge(event);
  }

  const lastResponse = event.request.session.slice(-1)[0];
  if (lastResponse.challengeResult === true) {
    return allow(event);
  } else if (countAttempts(event, false) === 0) {
    return customChallenge(event);
  }

  return customChallenge(event)
};

function allow(event) {
  console.log("Authentication allowed!");

  event.response.issueTokens = true;
  event.response.failAuthentication = false;

  return event;
}

function customChallenge(event) {
  event.response.issueTokens = false;
  event.response.failAuthentication = false;
  event.response.challengeName = "CUSTOM_CHALLENGE";

  return event;
}

function countAttempts(event, excludeProvideAuthParameters = true) {
  if (!excludeProvideAuthParameters) {
    return event.request.session.length;
  }

  return event.request.session.filter(
    (entry) => entry.challengeMetadata !== "PROVIDE_AUTH_PARAMETERS"
  ).length;
}

This Lambda is responsible for creating the actual challenge. In a typical custom auth flow (like sending an OTP), this function would generate a secret and send it to the user.

In our passkey flow, however, the “secret” is created and signed on the client side during the WebAuthn ceremony handled by Corbado Connect. Therefore, the only job of this Lambda is to pass the user’s cognitoID securely to the next step via privateChallengeParameters. This ID is essential for the verification step.

index.mjs

// This is the 2nd lambda in the Cognito custom auth flow
export const handler = async(event) => {
    console.log('Received event:', event);

    event.response = {
        challengeMetadata: 'CORBADO_CHALLENGE_COGNITO_CLAIM',
        // At least one public challenge parameter is required
        publicChallengeParameters: {
            "dummy": "dummy"
        },
        privateChallengeParameters: {
            "cognitoID": event.userName,
        }
    };

    console.log(event.response);

    return event;
};

This is the final and most critical Lambda in the chain. It’s responsible for verifying the user’s response to the challenge.

Its key responsibilities are:

Get Secret: It securely fetches the secret from AWS Systems Manager Parameter Store.
Call Corbado Backend API: It takes the signedPasskeyData (which is the user’s challengeAnswer) and the cognitoID and sends them to Corbado’s /v2/passkey/verifySignedData endpoint.
Return Result: Based on the response from Corbado’s Backend API, it sets event.response.answerCorrect to true or false, telling Amazon Cognito whether the user’s passkey authentication was successful.

index.mjs

// This is the 3rd lambda in the Cognito custom auth flow
import { SSMClient, GetParameterCommand } from '@aws-sdk/client-ssm';

// Full URL of Backend API (e.g. https://backendapi.cloud.corbado.io)
const corbadoBackendApiUrl = process.env.BAPI_URL;

// Name/path of Backend API secret in AWS Systems Manager Parameter Store
const corbadoBackendApiSecretPath = process.env.BAPI_SECRET_PATH;

// Backend API secret (base64-encoded projectID:API Secret for usage in Basic Auth header)
let corbadoBackendApiSecret = null;

// Fetch Backend API secret from AWS Systems Manager Parameter Store
const getCorbadoBackendApiSecret = async () => {
    if (corbadoBackendApiSecret) {
        return corbadoBackendApiSecret;
    }

    try {
        const ssm = new SSMClient();
        const command = new GetParameterCommand({
            Name: corbadoBackendApiSecretPath,
            WithDecryption: true
        });

        const response = await ssm.send(command);
        corbadoBackendApiSecret = response.Parameter.Value;

        return corbadoBackendApiSecret;
    } catch (error) {
        throw new Error(`Failed to fetch ${corbadoBackendApiSecretPath} from AWS Systems Manager Parameter Store: ${error.message}`);
    }
};

// Main handler function
export const handler = async (event) => {
    console.log('Received event:', event);

    // Check if all required fields are present
    if (!event.request.challengeAnswer || !event.request.privateChallengeParameters || !event.request.privateChallengeParameters.cognitoID) {
        console.log('Important event fields are missing');
        event.response.answerCorrect = false;

        return event;
    }

    const cognitoID = event.request.privateChallengeParameters.cognitoID;
    const signedPasskeyData = event.request.challengeAnswer;

    try {
        // Execute call to Backend API
        const basicAuth = await getCorbadoBackendApiSecret();
        const verifySignedDataRes = await fetch(`${corbadoBackendApiUrl}/v2/passkey/verifySignedData`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                Authorization: `Basic ${basicAuth}`,
                'Connection': 'close'
            },
            body: JSON.stringify({
                signedPasskeyData: signedPasskeyData,
                username: cognitoID
            })
        });

        // Check if call to Backend API was successful
        if (!verifySignedDataRes.ok) {
            console.log(`Call to ${corbadoBackendApiUrl}/v2/passkey/verifySignedData failed with status ${verifySignedDataRes.status} (Cognito ID: ${cognitoID})`);
            event.response.answerCorrect = false;

            return event;
        }

        // Check verification result
        const verifySignedDataResData = await verifySignedDataRes.json();
        if (verifySignedDataResData.verificationResult === "success") {
            console.log(`Verification successful (Cognito ID: ${cognitoID})`);
            event.response.answerCorrect = true;
        } else {
            console.log(`Verification failed (Cognito ID: ${cognitoID})`);
            event.response.answerCorrect = false;
        }

        return event;
    } catch (error) {
        console.error('Caught exception:', error);
        event.response.answerCorrect = false;

        return event;
    }
}

You need to configure these three Lambdas in your Amazon Cognito User Pool’s settings under User pool > Authentication > Extensions.

Hosting

The three custom authentication Lambda functions can be deployed in two different ways, depending on your chosen setup and requirements:

Corbado-Hosted: For ease of use and quicker setup, Corbado can manage and host these Lambda functions on your behalf within our secure AWS environment. This model simplifies maintenance and operations.
Self-Hosted: For organizations that require full control over their infrastructure for security, compliance, or customization reasons, you can deploy and manage these Lambda functions directly within your own AWS account.

Passkey Management

After users have created their initial passkeys during sign-up and used them for login, they need a way to manage their existing passkeys. Passkey management encompasses three main operations:

Viewing existing passkeys
Creating additional passkeys
Deleting unused passkeys

All these operations follow a similar pattern: they require obtaining a ConnectToken for the Corbado Connect UI component, which then handles the user interface and underlying functionality. In the following sections, we’ll focus on the passkey deletion process as an example, since the other operations follow a similar pattern.

The complete flow is illustrated in detail here.

Implementation Overview

The passkey deletion process consists of a series of interactions between the example application (utilizing AWS Amplify), Amazon Cognito, and Corbado APIs. These interactions are best illustrated using a sequence diagram:

UI Component Integration

We integrate the CorbadoConnectPasskeyList component from the @corbado/connect-react library. This component provides a complete user interface for managing passkeys, including viewing, adding, and deleting them.

Here’s how it’s used in our example application’s profile page:

/application/cognito/app/(auth-required)/profile/PasskeySection.tsx

'use client';

import {fetchAuthSession} from "aws-amplify/auth";
import {getConnectToken} from "@/app/(auth-required)/profile/actions";
import {CorbadoConnectPasskeyList} from "@corbado/connect-react";

type Props = {
    integratePasskeys: boolean;
};

export const PasskeySection = ({integratePasskeys}: Props) => {
    if (!integratePasskeys) {
        return (
            <div className='mb-2 w-full'>
                <div>Passkeys have not been integrated into this application.</div>
                <div>To integrate with 3 clicks. Use the button on the upper right side of this page.</div>
            </div>
        )
    }

    return (
        <div className='mb-2 w-full'>
            <CorbadoConnectPasskeyList
                connectTokenProvider={async (connectTokenType: string) => {
                    const session = await fetchAuthSession();
                    const idToken = session.tokens?.idToken?.toString();

                    return await getConnectToken(connectTokenType, idToken);
                }}
            />
        </div>
    )
}

For a detailed explanation of all available props for this component, please see the CorbadoConnectPasskeyList component documentation.

Obtaining the ConnectToken

When the component needs to perform an operation (like deleting a passkey), it executes the function given in connectTokenProvider to request a short-lived ConnectToken from Corbado’s Backend API. This token authorizes the specific operation for the authenticated user.

The frontend first gets the idToken for the currently logged-in user from AWS Amplify. This JWT proves the user’s session with Amazon Cognito. The idToken is then sent to a Next.js Server Action:

connectTokenProvider={async (connectTokenType: string) => {
    const session = await fetchAuthSession();
    const idToken = session.tokens?.idToken?.toString();

    return await getConnectToken(connectTokenType, idToken);
}}

The server action first verifies the idToken to ensure it’s valid and extracts the user’s identity, then requests the ConnectToken by calling the utility function getCorbadoConnectToken():

/application/cognito/app/(auth-required)/profile/actions.tsx

'use server';

import {getCorbadoConnectToken, verifyAmplifyToken} from "@/lib/utils";

export const getConnectToken = async (connectTokenType: string, idToken?: string) => {
    if (!idToken) {
        throw new Error('idToken is required');
    }

    const {displayName, identifier} = await verifyAmplifyToken(idToken);

    return getCorbadoConnectToken(connectTokenType, displayName, identifier);
}

The utility function then manages the request to the Corbado Backend API, using the provided connectTokenType to specify which operation the token should authorize (in this case, it could be ‘passkey-list’, ‘passkey-add’, or ‘passkey-delete’).

Overview

Flows

Architecture

UI Components

Integration

Features

Concepts

Security & Compliance

Amazon Cognito & Corbado Connect Passkey Integration

Introduction

How it Works

Example Application

Implementation Overview

UI Component Integration

Obtaining the ConnectToken

Updating MFA Settings

Implementation Overview

UI Component Integration

Identifier Translation

Custom Lambda functions

Secrets

Implementation

Hosting

Passkey Management

Implementation Overview

UI Component Integration

Obtaining the ConnectToken

Overview

Flows

Architecture

UI Components

Integration

Features

Concepts

Security & Compliance

​Introduction

​How it Works

​Example Application

​User Sign-up

​Implementation Overview

​UI Component Integration

​Obtaining the ConnectToken

​Updating MFA Settings

​User Login

​Implementation Overview

​UI Component Integration

​Identifier Translation

​Custom Lambda functions

​Secrets

​Implementation

​Hosting

​Passkey Management

​Implementation Overview

​UI Component Integration

​Obtaining the ConnectToken

Introduction

How it Works

Example Application

User Sign-up

Implementation Overview

UI Component Integration

Obtaining the ConnectToken

Updating MFA Settings

User Login

Implementation Overview

UI Component Integration

Identifier Translation

Custom Lambda functions

Secrets

Implementation

Hosting

Passkey Management

Implementation Overview

UI Component Integration

Obtaining the ConnectToken