or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication-lifecycle.mddevice-management.mdindex.mdmulti-factor-authentication.mdoauth-social-authentication.mdpassword-management.mdserver-side-apis.mdsession-management.mduser-management.mdwebauthn-credentials.md
tile.json

multi-factor-authentication.mddocs/

Multi-Factor Authentication

Complete MFA setup, management, and verification including TOTP, SMS, and email-based authentication.

Set Up TOTP

Initialize TOTP (Time-based One-Time Password) authentication for a user.

function setUpTOTP(): Promise<SetUpTOTPOutput>;

interface SetUpTOTPOutput {
  sharedSecret: string;
  getSetupUri: (appName: string, accountName?: string) => string;
}

Usage Example

import { setUpTOTP } from "@aws-amplify/auth";

const { sharedSecret, getSetupUri } = await setUpTOTP();

// Generate QR code URI for authenticator apps
const qrCodeUri = getSetupUri("MyApp", "user@example.com");

console.log("Scan this QR code with your authenticator app:", qrCodeUri);
console.log("Or manually enter this secret:", sharedSecret);

Verify TOTP Setup

Verify and complete the TOTP setup process with a code from the authenticator app.

function verifyTOTPSetup(input: VerifyTOTPSetupInput): Promise<void>;

interface VerifyTOTPSetupInput {
  code: string;
  friendlyDeviceName?: string;
}

Usage Example

import { verifyTOTPSetup } from "@aws-amplify/auth";

await verifyTOTPSetup({
  code: "123456",
  friendlyDeviceName: "My iPhone Authenticator"
});

console.log("TOTP setup completed successfully");

Update MFA Preference

Configure MFA preferences for a user including preferred and enabled MFA methods.

function updateMFAPreference(input: UpdateMFAPreferenceInput): Promise<void>;

interface UpdateMFAPreferenceInput {
  sms?: MFAPreference;
  totp?: MFAPreference;
}

type MFAPreference = 'ENABLED' | 'DISABLED' | 'PREFERRED' | 'NOT_PREFERRED';

Usage Example

import { updateMFAPreference } from "@aws-amplify/auth";

// Enable TOTP and set as preferred, disable SMS
await updateMFAPreference({
  totp: 'PREFERRED',
  sms: 'DISABLED'
});

// Enable both SMS and TOTP, prefer TOTP
await updateMFAPreference({
  sms: 'ENABLED',
  totp: 'PREFERRED'
});

console.log("MFA preferences updated");

Fetch MFA Preference

Get the current MFA preferences for a user.

function fetchMFAPreference(): Promise<FetchMFAPreferenceOutput>;

interface FetchMFAPreferenceOutput {
  enabled?: AuthMFAType[];
  preferred?: AuthMFAType;
}

type AuthMFAType = 'SMS' | 'TOTP';

Usage Example

import { fetchMFAPreference } from "@aws-amplify/auth";

const { enabled, preferred } = await fetchMFAPreference();

console.log("Enabled MFA methods:", enabled);
console.log("Preferred MFA method:", preferred);

// Example output:
// Enabled MFA methods: ['SMS', 'TOTP']
// Preferred MFA method: 'TOTP'

MFA During Sign In

When MFA is enabled, the sign-in flow will require additional verification:

import { signIn, confirmSignIn } from "@aws-amplify/auth";

// Initial sign in
const { isSignedIn, nextStep } = await signIn({
  username: "user@example.com",
  password: "MyPassword123!"
});

if (!isSignedIn) {
  switch (nextStep.signInStep) {
    case 'CONFIRM_SIGN_IN_WITH_SMS_CODE':
      console.log(`SMS code sent to: ${nextStep.codeDeliveryDetails?.destination}`);
      // Get SMS code from user and confirm
      const smsCode = "123456"; // from user input
      await confirmSignIn({ challengeResponse: smsCode });
      break;
      
    case 'CONFIRM_SIGN_IN_WITH_TOTP_CODE':
      console.log("Enter TOTP code from your authenticator app");
      // Get TOTP code from user and confirm
      const totpCode = "654321"; // from user input
      await confirmSignIn({ challengeResponse: totpCode });
      break;
      
    case 'CONTINUE_SIGN_IN_WITH_MFA_SELECTION':
      console.log("Available MFA methods:", nextStep.availableChallenges);
      // Let user choose preferred method for this session
      break;
      
    case 'CONTINUE_SIGN_IN_WITH_TOTP_SETUP':
      console.log("TOTP setup required");
      // Guide user through TOTP setup process
      break;
  }
}

MFA Best Practices

TOTP Setup Flow

  1. Call setUpTOTP() to get the shared secret and QR code URI
  2. Display QR code to user or show manual entry option
  3. User configures their authenticator app
  4. User enters a code from their app
  5. Call verifyTOTPSetup() with the code to complete setup
  6. Update MFA preferences as needed

Security Considerations

  • Always use secure transport (HTTPS) for MFA operations
  • Store TOTP shared secrets securely on the client side
  • Provide clear instructions for authenticator app setup
  • Handle MFA setup failures gracefully
  • Consider backup codes for account recovery

Error Handling

import { setUpTOTP, AuthError } from "@aws-amplify/auth";

try {
  const totpSetup = await setUpTOTP();
} catch (error) {
  if (error instanceof AuthError) {
    switch (error.name) {
      case 'NotAuthorizedException':
        console.log('User not signed in');
        break;
      case 'InvalidParameterException':
        console.log('Invalid request parameters');
        break;
      case 'ResourceNotFoundException':
        console.log('User pool configuration issue');
        break;
      default:
        console.log('TOTP setup failed:', error.message);
    }
  }
}