
## Introduction

`Time Based One Time Password (TOTP)` is a way of doing two factor authentication, it uses a shared secret and current time as input to generate numeric passwords which are available offline, apps like [Google Authenticator](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en_IN&gl=US), [Authy](https://authy.com/), and even password managers like [1Password](https://support.1password.com/one-time-passwords/#set-up-two-factor-authentication-for-a-website)

## Adding MFA using CDK

> To create a Cognito Userpool and add other configurations [read this blog](https://www.deznit.com/blog/aws-cognito-basic).

MFA can be set by specifying the `mfa` property in userpool. We can set MFA as `REQUIRED` or `OPTIONAL` . If set to `REQUIRED` and using [Amplify UI](https://ui.docs.amplify.aws/react/connected-components/authenticator) it will show an additional screen for configuring TOTP on user signup and will ask for OTP on user signin. If set to `OPTIONAL` we will have to handle the MFA flow ourself.

In this post we are looking at adding MFA using TOTP other way of MFA is using OTP from SMS for which user will require a verified phone number.

```tsx
const deznitUserpool = new cognito.UserPool(this, "deznituserpool", {
  // ...rest
  mfa: cognito.Mfa.REQUIRED,
  mfaSecondFactor: {
    sms: false,
    otp: true,
  },
});
```

After deploying the changes using `cdk deploy` we can check the AWS Console for the MFA configuration in `Sign-in experience` tab in the userpool.

<Image
  src="/images/posts/adding-mfa-tocognito-using-cdk-1.png"
  height={40}
  width={40}
  className="rounded-full self-start"
  alt="user image"
/>

## Frontend implementation

We will be creating a basic [NextJs](https://nextjs.org/) app with [AWS Amplify](https://aws.amazon.com/amplify/) you can use any frontend framework/library you like . Let’s create a nextjs app with typescript using the command below.

```bash
npx create-next-app@latest --typescript
```

### Adding Amplify

> You will need to install and configure Amplify cli on your machine if this is your first time using amplify. Please follow [this guide on amplify docs](https://docs.amplify.aws/start/getting-started/installation/q/integration/react/).

First step is to add amplify fro that we just need to run :

```bash
amplify init
```

from the root of the project, it will setup amplify and create a folder named `amplify` and file named `amplify-exports.js` in your src folder (if location is not changed).

After installation is complete `cd` into the folder and install the following packages . `@aws-amplify/ui-react` gives us some prebuilt ui components that we can easily use to add things like authentication.

```bash
npm install aws-amplify @aws-amplify/ui-react
```

### Authenticated page

Now to create a simple authenticated(protected) page replace `index.tsx` with the code below. Wrapping our component/page with`Authenticator` from `@aws-amplify/ui-react` will make it accessible only if logged in.

```tsx
import type { NextPage } from "next";
import Head from "next/head";
import styles from "../styles/Home.module.css";
import { Authenticator } from "@aws-amplify/ui-react";
import { Amplify } from "aws-amplify";
import awsExports from "../src/aws-exports";

Amplify.configure({ ...awsExports, ssr: true });

//  customization of form fields
//  https://ui.docs.amplify.aws/react/connected-components/authenticator/customization
const formFields = {
  signIn: {
    username: {
      labelHidden: true,
      placeholder: "Enter email",
      isRequired: true,
      label: "Enter your email",
    },
  },
  signUp: {
    username: {
      labelHidden: true,
      placeholder: "Enter email",
      isRequired: true,
      label: "Enter your email",
    },
  },
};

const Home: NextPage = () => {
  return (
    <div className={styles.container}>
      <Head>
        <title>Create Next App</title>
        <meta name="description" content="Generated by create next app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={styles.main}>
        <Authenticator formFields={formFields}>
          {({ signOut, user }) => (
            <div className={styles.card}>
              <h1 className={styles.title}>Hello</h1>
              <h4>{user?.attributes?.email}</h4>
              <button className={styles.btn} onClick={signOut}>
                Sign Out
              </button>
            </div>
          )}
        </Authenticator>
      </main>
    </div>
  );
};

export default Home;
```

We also need to add some styles for the Amplify Ui, import styles in `_app.tsx`.

```tsx
// _app.tsx
import "@aws-amplify/ui-react/styles.css";
```

To start the nextjs dev server `npm run dev` and we will be able to see the amplify auth ui on the home page.

<Image
  src="/images/posts/adding-mfa-tocognito-using-cdk-2.png"
  height={40}
  width={40}
  className="rounded-full self-start h-24 w-64"
  alt="user image"
/>

### Importing cognito userpool

As we created cognito userpool using cdk we will have to import the userpool to amplify project. Run the following command from root of the project

```bash
amplify import auth
```

This command will generate all the configuration required by amplify library an next push operation, and this imported cognito auth can be used by other services like lambda or api for authentication and authorization.

To create the configuration file run.

```bash
amplify push
```

Once that operation is complete you should see changes in `aws-exports.js` file and new properties added.

```tsx
const awsmobile = {
  aws_project_region: "YOUR_REGION",

  //newly added auth properties
  aws_cognito_region: "YOUR_REGION",
  aws_user_pools_id: "YOUR_USER_POOL_ID",
  aws_user_pools_web_client_id: "YOUR_USER_POOL_WEB_CLIENT_ID",
};
```

Now we can create a new account using email and password, as we have set MFA as `REQUIRED` we will be shown a screen to setup TOTP after we verify our email address. The screen will look something like this with a qr code that you have to scan with app like [Google Authenticator](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en_IN&gl=US) and enter the numeric code generated by app.

<Image
  src="/images/posts/adding-mfa-tocognito-using-cdk-3.png"
  height={40}
  width={40}
  className="rounded-full self-start h-24 w-64 shadow-lg"
  alt="user image"
/>

Once the TOTP setup is done everytime you sign in you will be asked for an otp from the authenticator app.

> You can also handle all this flow manually with the help of api from aws cognito [read the docs here](https://ui.docs.amplify.aws/react/connected-components/authenticator/headless)


Adding MFA(TOTP) to AWS Cognito with CDK


## Introduction

[Amazon cognito](https://aws.amazon.com/cognito/) userpool is a secure identity store that lets you add user sign-up, sign-in, and access control to aws resources from your web and mobile apps quickly and easily. An App client is an entity within userpool that lets you call unauthenticated api like signin, signup from your app, App client have an app id and optional secure secret so that only authorised client app can call these unauthorised apis.

## Getting started

We will be writing cdk code in typescript and will use CDK toolkit `aws-cdk` to initialise a starter project. We will first create a new folder `cdk-cognito-userpool` and `cd` into the folder, the name of the folder will be used by cdk toolkit to name the stack but it can be changed later.

```bash
mkdir cdk-cognito-userpool
cd cdk-cognito-userpool
```

We can now run the following command to initialise project will be using the default `app` template.

```bash
npx aws-cdk init app --language=typescript
```

Only dependency that we have to add is `aws-cdk-lib`

```bash
npm i aws-cdk-lib
```

## Defining Stack

We will define the stack inside `lib > cdk-cognito-userpool-stack.ts` . Lets start by creating a userpool basic and we will add configuration option later on.

### Userpool

We will use the `Userpool` construct from cognito to create userpool.

- `userPoolName` property can be used to define a custom name for cogninto userpool resource. If this property is not defined CloudFormation will automatically generate a name for the resource.
- `selfSignUpEnabled` if this is set to `false` then a user can only be signed up by admin.

```tsx
import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";
import * as cognito from "aws-cdk-lib/aws-cognito";

export class CdkCognitoUserpoolStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const deznitUserpool = new cognito.UserPool(this, "deznituserpool", {
      /**
       * you can specify userPoolName if not cloudformation will generate a name
       */
      userPoolName: "deznit-userpool",
      /**
       * if false user can only be invided by admin
       */
      selfSignUpEnabled: true,
    });
  }
}
```

### Customising emails

- `userVerification`is used to customise the email sent to user on signup.
- `userInvitation` is email sent to user when a new user is created by admin.
- `emailStyle` have two options `cognito.VerificationEmailStyle.CODE` which sends an otp, and `cognito.VerificationEmailStyle.LINK` which will send a verification link in the email.
- You can use HTML tags inside `emailBody` for styling. if you use `CODE` as verification type the emailBody must contain `{###}` as a placeholder to insert OTP by cognito. If you use `LINK` then emailBody must contain `{##Verify Your Email##}` as placeholder for the link.

```tsx
const deznitUserpool = new cognito.UserPool(this, "deznituserpool", {
  // ... rest

  /**
   * customizing verification email
   */
  userVerification: {
    emailStyle: cognito.VerificationEmailStyle.CODE,
    emailSubject: "Deznit email verification",
    emailBody:
      "Thanks for signing up to Deznit Your verification code is {####}",
  },

  /**
   * customising admin invite
   */
  userInvitation: {
    emailSubject: "Invitation to join Deznit",
    emailBody:
      "Hello {username}, you have been invited to join Deznit. Your temporary password is {####}",
  },
});
```

> The maximum length for the message, including the verification code (if present), is 20,000 UTF-8 characters

### Sign In

There are 4 different methods (`username`, `email` , `phone` , `prefferedUsername` ) to let users signin to your app. `This cannot be changed once userpool is created` .

- `username` is immutable, user will have to set an username at the time of signup.
- `prefferedUsername` this is mutable and only available if username option is set to true.

> If email address is selected as an alias, Amazon Cognito doesn't accept a user name that matches a valid email address format. Similarly, if you select phone number as an alias, Amazon Cognito doesn't accept a user name for that user pool that matches a valid phone number format.

- Aliases can only be used for signin if its verified so it’s important to set `autoVerify` to true for the aliases.
- If you want to ignore case checking for aliases like username you can set `signInCaseSensitive` to false, default value is true.
- Password policy can be configured using the `passwordPolicy` property. `temporaryPasswordValidityDays` is the validity to password generated when a user is invited to app, if user doesn’t signup in the timeframe admin will have to reset the password.
- `accountRecovery` is how user will be able to recover their account if they forget their password. Default value is phone if available otherwise email. User wont be able to use phone for recovery if it is used for MFA.

```tsx
const deznitUserpool = new cognito.UserPool(this, "deznituserpool", {
  // ...rest
  signInAliases: { email: true },
  /**
   * cognito will request verification for following
   */
  autoVerify: { email: true },
  signInCaseSensitive: false, //default true

  passwordPolicy: {
    minLength: 6,
    requireDigits: true,
    requireLowercase: false,
    requireUppercase: false,
    requireSymbols: false,
    temporaryPasswordValidityDays: 30,
  },
  /**
   * This is how user will be able to recover their account
   */
  accountRecovery: cognito.AccountRecovery.EMAIL_ONLY,
});
```

### Attributes

We can associate attributes with a cognito user. Cognito have some predefined attributes called `standardAttributes` which when set as `required` user wont be able to signup without providing that info. Apart from the standard attributes we can also set am maximum of 50 `customAttributes` also.

```tsx
const deznitUserpool = new cognito.UserPool(this, "deznituserpool", {
  // ...rest

  /**
   * Standard attributes that cognito supports
   * if required user wont be able to signup unless that attribute is provided
   */
  standardAttributes: {
    fullname: {
      required: false,
      mutable: true,
    },
    gender: {
      required: false,
      mutable: true,
    },
  },
  /**
   * custom attributes for a user
   * max 50
   */
  customAttributes: {
    isAdmin: new cognito.BooleanAttribute({ mutable: true }),
    level: new cognito.StringAttribute({ mutable: true }),
  },
});
```

With this we have setup a basic cognito userPool, there are many other features like setting MFA, SES for sms and lambda triggers etc. which I will cover in future posts. Now below the userpool let’s create a Userpool App Client.

### Removal policy

`removalPolicy` specify if we want to `DESTROY` or `RETAIN` the userPool on running `cdk destroy`. Default value is `RETAIN`.

```tsx
const deznitUserpool = new cognito.UserPool(this, "deznituserpool", {
  // ...rest

  /**
   * Deletes the userpool on cdk destroy
   * default is RETAIN
   */
  removalPolicy: cdk.RemovalPolicy.DESTROY,
});
```

## App Client

An App client lets you call unauthenticated api like signin, signup from your app, App client have an app id and optional secure secret so that only authorised client app can call these unauthorised apis.

- `cognito.ClientAttributes()` can be used to grant read and write permissions to cognito attributes from client app.
- Read and write permissions can be provided to both `standardAttributes` and `customAttributes`
- Provide permissions to only those attributes which you need. For example you should not give write permissions to attributes like `isAdmin`

```tsx
const deznitUserpool = new cognito.UserPool(this, "deznituserpool", {
  // ...userpool configuration
});

/**
 * userpool client permissions to write read attributes
 */

const clientWriteAttributes = new cognito.ClientAttributes()
  .withStandardAttributes({ fullname: true, gender: true })
  .withCustomAttributes("isAdmin", "level");

const clientReadAttributes = clientWriteAttributes
  .withStandardAttributes({
    fullname: true,
    gender: true,
    emailVerified: true,
    preferredUsername: true,
  })
  .withCustomAttributes("isAdmin", "level");

/**
 * Adding userpool client
 */

const userpoolClient = deznitUserpool.addClient("app-client", {
  userPoolClientName: "deznit-app-client",

  readAttributes: clientReadAttributes,
  writeAttributes: clientWriteAttributes,
});
```

## Final Code

```tsx
import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";
import * as cognito from "aws-cdk-lib/aws-cognito";

export class CdkCognitoUserpoolStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const deznitUserpool = new cognito.UserPool(this, "deznituserpool", {
      /**
       * you can specify userPoolName if not cloudformation will generate a name
       */
      userPoolName: "deznit-userpool",
      /**
       * if false user can only be invided by admin
       */
      selfSignUpEnabled: true,

      /**
       * customizing verification email
       */
      userVerification: {
        emailStyle: cognito.VerificationEmailStyle.CODE,
        emailSubject: "Deznit email verification",
        emailBody:
          "Thanks for signing up to Deznit Your verification code is {####}",
      },
      /**
       * customising admin invite
       */
      userInvitation: {
        emailSubject: "Invitation to join Deznit",
        emailBody:
          "Hello {username}, you have been invited to join Deznit. Your temporary password is {####}",
      },
      /**
       * ways by which users can signin
       * 4 options --> username, email, phone, preferredUsername
       *
       */
      signInAliases: { email: true },
      /**
       * cognito will request verification for following
       */
      autoVerify: { email: true },
      signInCaseSensitive: false,

      passwordPolicy: {
        minLength: 6,
        requireDigits: true,
        requireLowercase: false,
        requireUppercase: false,
        requireSymbols: false,
      },

      /**
       * Standard attributes that cognito supports
       * if required user wont be able to signup unless that attribute is provided
       */
      standardAttributes: {
        fullname: {
          required: false,
          mutable: true,
        },
        gender: {
          required: false,
          mutable: true,
        },
      },
      /**
       * custom attributes for a user
       * max 50
       */
      customAttributes: {
        isAdmin: new cognito.BooleanAttribute({ mutable: true }),
        level: new cognito.StringAttribute({ mutable: true }),
      },

      accountRecovery: cognito.AccountRecovery.EMAIL_ONLY,

      /**
       * The email from which cognito sends email
       * for higher volume use Amazon SES
       */
      email: cognito.UserPoolEmail.withCognito("info@deznit.com"),

      /**
       * Deletes the userpool on cdk destroy
       * default is RETAIN
       */
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });

    /**
     * userpool client permissions to write read attributes
     */

    const clientWriteAttributes = new cognito.ClientAttributes()
      .withStandardAttributes({ fullname: true, gender: true })
      .withCustomAttributes("isAdmin", "level");

    const clientReadAttributes = clientWriteAttributes
      .withStandardAttributes({
        fullname: true,
        gender: true,
        emailVerified: true,
        preferredUsername: true,
      })
      .withCustomAttributes("isAdmin", "level");

    /**
     * Adding userpool client
     */

    const userpoolClient = deznitUserpool.addClient("app-client", {
      userPoolClientName: "deznit-app-client",

      readAttributes: clientReadAttributes,
      writeAttributes: clientWriteAttributes,
    });

    /**
     * print values to console
     */
    new cdk.CfnOutput(this, "aws_user_pools_id", {
      value: deznitUserpool.userPoolId,
    });

    new cdk.CfnOutput(this, "aws_user_pools_web_client_id", {
      value: userpoolClient.userPoolClientId,
    });
  }
}
```

- To synthesize and print cloudformation template run

```bash
cdk synth
```

- To deploy the stack to aws run

```bash
cdk deploy
```

- To test the userpool lets create a new user using the [aws cli create-admin-user](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/admin-create-user.html). You can find YOUR_USERPOOL_ID from `cdk-exports.ts` file create after cdk deploy.

```bash
aws cognito-idp admin-create-user \
  --user-pool-id YOUR_USER_POOL_ID \
  --username deznit.text@gmail.com

```

You will get response similar to this after successful creation of user in cognito and in aws console you will be able to see the newly created user, an email will be sent with temporary password to the user.

```js
{
  "User": {
    "Username": "59be41de-2c0e-4e4f-adf4-945b5fd2a56e",
    "Attributes": [
      {
        "Name": "sub",
        "Value": "59be41de-2c0e-4e4f-adf4-945b5fd2a56e"
      },
      {
        "Name": "email",
        "Value": "deznit.text@gmail.com"
      }
    ],
    "UserCreateDate": "2022-10-08T11:39:22.261000+05:30",
    "UserLastModifiedDate": "2022-10-08T11:39:22.261000+05:30",
    "Enabled": true,
    "UserStatus": "FORCE_CHANGE_PASSWORD"
  }
}
```

<Image
  src="/images/posts/aws-cognito-basic-1.png"
  height={40}
  width={40}
  className="rounded-full self-start"
  alt="user image"
/>

- To delete the stack run the following command (if removalPolicy is set to DESTROY it will delete the userpool and all the user data)

```bash
cdk destroy
```


Create AWS Cognito UserPool using CDK


## Introduction

Sometimes we want to run multiple async operations simultaneously and aggregate the result of promises before moving forward. Both Promis.all() and Promise.allSettled() help in doing that. Both look similar in terms of syntax.

```js
const promise1 = new Promise((resolve, reject) => {
  resolve(1);
});

const promise2 = new Promise((resolve, reject) => {
  resolve("Two");
});

Promise.all([promise1, promise2])
  .then((result) => console.log(result)) // [ 1, 'Two' ]
  .catch((err) => console.log(`error ${err}`));

Promise.allSettled([promise1, promise2])
  .then((result) => console.log(result)) // [{ status: 'fulfilled', value: 1 },{ status: 'fulfilled', value: 'Two' }]
  .catch((err) => console.log(`error ${err}`));
```

## What are the differences between them?

There are two differences between them.

### Promises rejection

Promise.all() have fail fast behaviour i.e as soon as any one of the input promise passed to `.all()` is rejected Promise.all() will be rejected. But `Promise.allSettled()` will wait for all input promises to finish and return a result even if any one of the input promise is rejected.

### Promise result

When all input promises have resolved `Promise.all()` return an array of result values. `.allSettled()` returns an array of objects with properties `status`, `value`, `reason`.

- `status` will be `fullfilled` or `rejected`.
- `value` property will only exist if the input promise resolved successfully i.e status is fullfilled.
- `reason` contains the reason why promise was rejected and only exists when status is rejected.

```js
const promise1 = new Promise((resolve, reject) => {
  resolve(1);
});

// rejecting promise
const promise2 = new Promise((resolve, reject) => {
  reject("Rejecting promise2");
});

Promise.all([promise1, promise2])
  .then((result) => console.log(result))
  .catch((err) => console.log(`error ${err}`));
// output ->  error Rejecting promise2

Promise.allSettled([promise1, promise2])
  .then((result) => console.log(result))
  .catch((err) => console.log(`error ${err}`));

/**
Output 
[
  { status: 'fulfilled', value: 1 },
  { status: 'rejected', reason: 'Rejecting promise2' }
]
 * */
```


Featured Article

Create AWS Cognito UserPool using CDK

Adding MFA(TOTP) to AWS Cognito with CDK

Promise.all() vs Promise.allSettled()