corbado / passkeys-amazon-cognito

Sample project that shows how to integrate passkeys into your existing password-based Amazon Cognito project.

Passkeys integration into Amazon Cognito

Sample project that shows how to integrate passkeys into your existing password-based Amazon Cognito project.

View passkeys demo · Report Bug · Request Feature

Overview

Passkeys are the new standard for authentication on the web. Currently, they're being rolled out by Apple, Google and Microsoft. Though, not many code sample projects exist, and even less for integrating them into existing authentication and user management systems. We provide a guide that shows how to easily add passkeys into your existing Amazon Cognito project.

For this sample, we leverage Corbado's passkey-first web components that let you integrate it in <1 hour, while still keeping Amazon Cognito as core user management system.

Find a detailed step-by-step tutorial here.

(back to top)

Built With

The sample project uses Angular as web frontend framework and Node.js / Express in the backend (both in TypeScript).

• 
• 
• 

(back to top)

Getting Started

We provide a docker file for quickly getting started. Note that you need to enter Amazon Cognito and Corbado environment variables to get things working (see docker-compose.yml).

To start project without locally without Docker, you need to run the Corbado CLI. Besides, you may also need to copy the AWS CLI credentials from .aws/credentials:

AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=

COGNITO_REGION=
COGNITO_USER_POOL_ID=
COGNITO_CLIENT_ID=
COGNITO_CLIENT_SECRET=
COGNITO_JWKS=

CORBADO_PROJECT_ID=
CORBADO_API_SECRET=
CORBADO_CLI_SECRET=
CORBADO_WEBHOOK_USERNAME=
CORBADO_WEBHOOK_PASSWORD=

Start the docker containers with:

docker compose up

Integration

Please see this link for a detailed step-by-step tutorial on how to integrate passkeys into Amazon Cognito.

Sign-up flow

The following steps provide a high-level overview what happens during the passkey sign-up flow.

1. Sign-up via Corbado web component on Angular frontend
2. Sign-up handled by Corbado backend (existing users are checked via webhooks)
3. Redirect to /api/corbado/authTokenValidate on Node.js / Express backend with corbadoAuthToken
4. API call to Corbado backend to verify corbadoAuthToken (API returns email)
5. API calls to create the user in Amazon Cognito
   1. AdminCreateUser (email=email returned from previous step, email_verified=true, custom:createdByCorbado=true)
   2. AdminSetUserPassword (Username=email, Password=randomPassword)
6. API calls to create session in Amazon Cognito
   1. AdminInitiateAuthCommand (AuthFlow=CUSTOM_AUTH, USERNAME=email returned from previous step, no password)
   2. AWS Lambda functions are executed
      1. Define auth challenge: Cognito invokes this trigger to initiate the custom auth flow
      2. Create auth challenge: Cognito invokes this trigger after Define auth challenge to create custom challenge
      3. Verify auth challenge response: Cognito invokes this trigger to verify response from user for custom challenge
   3. RespondToAuthChallenge
7. Amazon Cognito returns JWTs (idToken, accessToken, refreshToken)
8. accessToken "saved in Angular"
9. Logged-in page in Angular verifies accessToken in JavaScript

Login flow

The following steps provide a high-level overview what happens during the passkey login flow.

1. Login via Corbado web component on Angular frontend
2. Login handled by Corbado backend (existing users are checked via webhooks)
3. Redirect to /api/corbado/authTokenValidate on Node.js / Express backend with corbadoAuthToken
4. API call to Corbado backend to verify corbadoAuthToken (API returns email)
5. API calls to create session in Amazon Cognito
   1. AdminInitiateAuthCommand (AuthFlow=CUSTOM_AUTH, USERNAME=email returned from previous step, no password)
   2. AWS Lambda functions are executed
      1. Define auth challenge: Cognito invokes this trigger to initiate the custom auth flow
      2. Create auth challenge: Cognito invokes this trigger after Define auth challenge to create custom challenge
      3. Verify auth challenge response: Cognito invokes this trigger to verify response from user for custom challenge
   3. RespondToAuthChallenge
6. Amazon Cognito returns JWTs (idToken, accessToken, refreshToken)
7. accessToken "saved in Angular"
8. Logged-in page in Angular verifies accessToken in JavaScript

(back to top)

Contact

Vincent Delitz - @vdelitz - [email protected]

Project link: https://github.com/corbado/passkeys-amazon-cognito

Tutorial link: https://www.corbado.com/blog/passkeys-amazon-cognito

(back to top)