Setup Amazon Cognito TOTP Software Token MFA using .net SDK

I have been working for a Dotnet Core API that uses a Cognito user pool to manage and authenticate users. There was a task to add functionalities to set up Time based one-time (TOTP) passwords for the API using AWS .net SDK. Eventually, I manage to find out required three AWS .net SDK calls to set up TOTP MFA. And they are

  1. AssociateSoftwareTokenAsync to get the QR code
  2. VerifySoftwareTokenAsync to verify the token
  3. Finally, SetUserMFAPreferenceAsync to enable SoftwareTokenMfa

However, One of my colleagues has already created a Github repo to demonstrate this MFA. In addition, I am adding a brief description below for these three requests. And MFA is –

Multi-factor authentication (MFA) increases security for your app by adding another authentication method, and not relying solely on user name and password. You can choose to use SMS text messages, or time-based one-time (TOTP) passwords as second factors in signing in your users.

Adding Multi-Factor Authentication (MFA) to a User Pool

Setup TOTP MFA using AWS .Net SDK

  • NuGet Package: AWSSDK.CognitoIdentityProvider
  • Create an instance of AmazonCognitoIdentityProviderClient . I named the variable cognito
  • User must pass a valid user credential to get access token. AdminInitiateAuthAsync can be used to retrieve a valid access token
  • For all the requests a valid access token is required

1. Generating otpauth Url

Firstly, you need to prived an opauth URL so that frontend can show the QR Code to the user. User needs to scan the QR code into his phone app to set up the TOTP MFA. Therefore, AssociateSoftwareTokenAsync is there to return a unique generated shared secret key code for the user account.

var request = new AssociateSoftwareTokenRequest
                     AccessToken = accessToken
var softwareTokenResponse = await cognito.AssociateSoftwareTokenAsync(request);
return  $"otpauth://totp/AWSCognito:{username}?secret={softwareTokenResponse.SecretCode}&issuer=MakeMeFamous";

2. Verify Token

Now, a user needs to scan the QR code in an app (e.g. Google Authenticator) to add your application into the device. And then the user needs to pass the Code and system will verify the token before enabling the TOTP MFA

await cognito.VerifySoftwareTokenAsync(new VerifySoftwareTokenRequest
                AccessToken = accessToken,
                UserCode = user.Token,
                FriendlyDeviceName = "MakeMeFamous Device"

Its response with VerifySoftwareTokenResponseTypestatus. It can be SUCCESS or ERROR

3. Enable MFA

Finally, you need to turn on the MFA preference in the Cognito user pool for the user.

await cognito.SetUserMFAPreferenceAsync(new SetUserMFAPreferenceRequest
                AccessToken = accessToken,
                SoftwareTokenMfaSettings = new SoftwareTokenMfaSettingsType
                    {Enabled = true, PreferredMfa = true}

Next time the user wants to login he/she will be challenged to pass a valid TOTP code

That’s all for today. Please feel free to comment to help me improving the blog. Finally, you’ll find my other cognito related posts here.

I would like to hear your thoughts