By Siva Rajamani, Principal Solutions Architect – AWS
By Manik Kakar, Chief Architect – 1Kosmos


Online account security is a top priority at Amazon Web Services (AWS), which is why, beginning in 2024, AWS will be growing its multi-factor authentication (MFA) requirements to further strengthen security for account holders.

MFA enhances security for web and mobile applications by requiring additional identification methods other than a password. It can also reduce the risk of user account takeover, phishing attacks, and password theft.

With biometric authentication capabilities, such as TouchID (fingerprint) and FaceID, among other options, users can have an even higher level of account security while being able to log into accounts more easily.

Providing a frictionless user experience with MFA often requires a variety of authentication options that support a range of users and devices. 1Kosmos BlockID and Amazon Cognito can help to balance security with usability when building customer facing applications.

In this post, we will how you how to integrate 1Kosmos BlockID step-up authentication into your Amazon Cognito sign-in flow. This offers a wide range of MFA options to your customers to enhance security while prioritizing user experience.

1Kosmos is an AWS Partner and AWS Marketplace Seller that provides BlockID and passwordless MFA for improved online account security. The platform is FIDO2 and NIST 800-63-3 certified.

How 1Kosmos BlockID Fits into Amazon Cognito

1Kosmos BlockID offers customers a strong MFA platform that can also have user identities validated based on NIST 800-63-3 Identity Assurance Level (IAL) proofing, which requires a physical presence for identification.

BlockID automatically delivers Identity Assurance Level 2 (IAL2) identity proofing and Authentication Assurance Level 2 (AAL2) user authentication. User data is encrypted in a private, permissioned blockchain.

BlockID MFA supports one-time password (OTP) via SMS and email, time-based one-time password (TOTP) from a linked mobile authenticator, and push notifications.

Amazon Cognito user pools are user directories for AWS customers to manage user identities. You can add sign-in, sign-up, and user management features to your customer-facing web and mobile applications.

Amazon Cognito user pools enable you to build a custom authentication flow that validates users based on one or more challenge/response cycles. You can use this flow to integrate BlockID step-up authentication into your validation process as a custom challenge, as depicted in Figure 1.

Using BlockID MFA with Amazon Cognito enables you to choose the best adaptive MFA methods such as biometrics, FIDO2 , or OTP through email and SMS that meets the needs of your application ecosystem.


Figure 1 – User authentication with BlockID using custom authentication flow.

To integrate BlockID step-up into the sign-in flow as a custom challenge, you’ll need to generate an OpenID Connect (OIDC) request and load the BlockID MFA user interface (UI) in an iframe.

When the user answers the challenge, a code grant is returned to your web application and can be sent to Amazon Cognito for verification. If the response is valid, the MFA challenge is successful and Cognito issues the application bearer tokens, which might include identity, access, and refresh tokens.

Testing Functionality Through BlockID Developer Portal

To try BlockID MFA integration ahead of a production integration, you can test functionality with 1Kosmos Developer Portal through the following steps:

Note that when you register an Amazon Cognito user, remember to use the same email address registered with developer portal.

For production, you’ll need a 1Kosmos BlockID tenant. Once set up, you will have tenantDNS, communityName, OAuth client ID, and a secret. For any support to set up on production, contact [email protected]. In addition, 1Kosmos has published open source code to make it easier for customers to integrate BlockID MFA into their web applications

Implementation Step-by-Step Guide

Let’s walk through the end-to-end flow of integrating BlockID MFA with Amazon Cognito using a custom authentication flow.

The first step is to deploy the AWS CloudFormation stack as described in the demo project. Once the CloudFormation is set up, you’ll need to get the user-pool-id and app-client-id from the outputs of the created CloudFormation stack, and provide the same in the placeholders in client code (public/view-client.js). The final step is to install and run the application.

This GitHub demo project provides the sample code to create a working demo in your environment with complete step-by-step deployment instructions.

A few implementation details to be aware of:

  • The AWS CloudFormation template creates an Amazon Cognito user pool, application client, and AWS Lambda triggers for the custom authentication.
  • The template also accepts tenantDNS, communityName, oauth clientID, and oauth client secret as inputs.
  • For security, parameters are masked in the CloudFormation console and stored in a secret in AWS Secrets Manager with a resource policy that provides relevant Lambda functions read access to that secret.
  • 1Kosmos settings are retrieved from AWS Secrets Manager at the initialization of the create OIDC request and during the exchange of code grant for an id_token.

Authentication Flow

This section describes how authentication happens between the client application, Amazon Cognito and the 1Kosmos BlockID MFA.


Figure 2 – Chart showing what the authentication flow looks like.

In your frontend application, the user is presented with a sign-in UI that performs the first factor authentication with username and password against the Amazon Cognito user pool. After the first factor, the Define Auth Challenge Lambda trigger will return CUSTOM_CHALLENGE, and this will move control to the Create Auth Challenge trigger.

The Create Auth Challenge Lambda trigger creates a BlockID OIDC request parameter using tenant ID, communityName, client ID. This is also where you can specify Authentication Context Class Reference (ACR) claims to configure what kind of step-up options should be available to a user.

Here’s a sample demonstrating what the Create Auth Challenge should look like.

Next, the web frontend (client) initializes the BlockID web library with the OIDC and displays BlockID MFA in an iframe to request a second factor from the user.

The BlockID library is initialized with the challenge parameters sent by the Create Auth Challenge Lambda function, which includes the following 1Kosmos parameters: tenant ID, communityName, OIDC client ID, ACR claim, username, and a callback function to invoke after MFA step is completed by the user.

The client-side code for configuring the BlockID library is shown below:


Through the BlockID iframe, the user can select MFA preferences and respond to an MFA challenge. After successful MFA setup, an OIDC code-grant response from the software development kit (SDK) will be returned to the client and passed to the mfa_callback function that was provided in BIDStepup.stepup call.


Figure 3 – MFA options are on the left side and email code-based MFA on the right.

The client sends the BlockID code-grant response to the Amazon Cognito service as a challenge response. Amazon Cognito sends the response to the Verify Auth Challenge Lambda trigger, which uses BlockID OIDC client ID and secret to verify the response.

Validation results and current state pass to the Define Auth Challenge Lambda trigger. If the user response is valid, then the BlockID MFA challenge is successful.

You can introduce additional challenges to the user or issue tokens and complete the authentication process.


Figure 4 – Amazon Cognito issued tokens after successful Auth Challenge response.


In this post, we showed how to integrate 1Kosmos BlockID with Amazon Cognito to support multi-factor authentication (MFA) capabilities for authentication in web and mobile applications. We also provided a step-by-step guide for application and website owners to integrate BlockID into Amazon Cognito to enhance online security.

Visit the demo application and review the code samples to learn how to integrate this with your application. You can also learn more about 1Kosmos in AWS Marketplace.


1Kosmos – AWS Partner Spotlight

1Kosmos is an AWS Partner that provides BlockID and passwordless MFA for improved online account security. The platform is FIDO2 and NIST 800-63-3 certified.

Contact 1Kosmos | Partner Overview | AWS Marketplace