tessl/npm-aws-amplify--auth

Authentication category of AWS Amplify providing APIs and building blocks for creating authentication experiences with Amazon Cognito

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Multi-Factor Authentication

Name: tessl/npm-aws-amplify--auth
Author: tessl

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

Call setUpTOTP() to get the shared secret and QR code URI
Display QR code to user or show manual entry option
User configures their authenticator app
User enters a code from their app
Call verifyTOTPSetup() with the code to complete setup
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);
    }
  }
}