MFA Management on AuthOS Docs | Auth Operating System API and SDK Guides

MFA Enrollment

Mon, 01 Jan 0001 00:00:00 +0000

Complete the MFA prerequisites before beginning enrollment. AuthOS MFA is Beta: test the exact authenticator applications and recovery policies you support because public interoperability and abuse-case evidence is still incomplete.

Checking MFA Status

Before enabling or managing MFA, check whether the authenticated user already has it enabled.

Basic Status Check

import { SsoClient } from '@drmhse/sso-sdk';

const sso = new SsoClient({
  baseURL: 'https://sso.example.com',
  token: accessToken
});

async function checkMfaStatus() {
  try {
    const status = await sso.user.mfa.getStatus();

    console.log('MFA enabled:', status.enabled);

    if (status.enabled) {
      console.log('MFA is currently active');
    } else {
      console.log('MFA is not enabled');
    }

    return status.enabled;
  } catch (error) {
    console.error('Failed to check MFA status:', error);
    return false;
  }
}

React Component for MFA Status

import { useState, useEffect } from 'react';
import { SsoClient } from '@drmhse/sso-sdk';

interface MfaStatusProps {
  sso: SsoClient;
}

export function MfaStatus({ sso }: MfaStatusProps) {
  const [enabled, setEnabled] = useState<boolean | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    checkStatus();
  }, []);

  const checkStatus = async () => {
    try {
      const status = await sso.user.mfa.getStatus();
      setEnabled(status.enabled);
    } catch (error) {
      console.error('Failed to check MFA status:', error);
    } finally {
      setLoading(false);
    }
  };

  if (loading) {
    return <div>Loading MFA status...</div>;
  }

  return (
    <div className="mfa-status">
      <h3>Two-Factor Authentication</h3>
      {enabled ? (
        <div className="status-enabled">
          <span className="badge success">Enabled</span>
          <p>Your account is protected with 2FA</p>
        </div>
      ) : (
        <div className="status-disabled">
          <span className="badge warning">Disabled</span>
          <p>Add an extra layer of security to your account</p>
        </div>
      )}
    </div>
  );
}

Setting Up TOTP MFA

The setup sequence has three required steps:

MFA Verification

Mon, 01 Jan 0001 00:00:00 +0000

Start after enrolling an authenticator application. Verification is required both to activate the factor and to exchange a pre-authentication token for a full login session.

Verifying TOTP Code to Enable MFA

After the user scans the QR code, require one current TOTP code before treating MFA as enabled.

Verification

import { SsoApiError } from '@drmhse/sso-sdk';

async function verifyAndEnableMfa(code: string) {
  try {
    const result = await sso.user.mfa.verify(code);

    console.log('MFA enabled successfully!');
    console.log('Backup codes:', result.backup_codes);

    // IMPORTANT: Display backup codes to user.
    // The user MUST save these before continuing.
    return result.backup_codes;
  } catch (error) {
    if (error instanceof SsoApiError) {
      console.error('Invalid code:', error.message);
    }
    throw error;
  }
}

Important: Backup codes are shown only once during setup. Require the user to save them securely before leaving the flow, and never send them to logs or analytics.

MFA Backup and Recovery

Mon, 01 Jan 0001 00:00:00 +0000

Each user receives 10 single-use backup codes during MFA setup. Recovery is part of the security boundary: show codes only when generated, keep them out of logs, and define a verified support path before users can lose access.

Managing Backup Codes

Regenerating Backup Codes

Regeneration invalidates every previous backup code. Warn the user and require an explicit confirmation before continuing.

async function regenerateBackupCodes() {
  try {
    const result = await sso.user.mfa.regenerateBackupCodes();

    console.log('New backup codes:', result.backup_codes);

    // IMPORTANT: Display new codes to the user once.
    // Previous codes are now invalid.
    return result.backup_codes;
  } catch (error) {
    console.error('Failed to regenerate backup codes:', error);
    throw error;
  }
}

The console.log calls above are illustrative. Remove them in production so recovery credentials never enter browser or observability logs.

MFA Administration

Mon, 01 Jan 0001 00:00:00 +0000

Disabling MFA removes the TOTP requirement and invalidates all backup codes. Use it only as an authenticated self-service action or after a documented, independent administrator recovery check.

Disabling MFA

Disable MFA

async function disableMfa() {
  try {
    const result = await sso.user.mfa.disable();

    console.log(result.message);
    // "MFA disabled successfully"

    return true;
  } catch (error) {
    console.error('Failed to disable MFA:', error);
    return false;
  }
}

After disablement, update the UI from a fresh status response and make the user complete a new enrollment flow if they choose to restore MFA.

MFA UI Integration

Mon, 01 Jan 0001 00:00:00 +0000

Build the account-security surface from focused controls rather than duplicating the full MFA protocol in one component:

Use MfaStatus and MfaSetupFlow from Enrollment.
Use LoginWithMfaForm from Verification in the sign-in surface.
Use BackupCodesManager from Backup and recovery.
Use DisableMfa from Administration.

Keep secret and backup-code state only as long as the active screen needs it. Do not place TOTP secrets, pre-authentication tokens, or recovery codes in URLs, analytics events, logs, or persistent browser storage.

MFA Troubleshooting and Security

Mon, 01 Jan 0001 00:00:00 +0000

AuthOS MFA is Beta. Test the complete enrollment, verification, backup-code, disablement, and administrator recovery paths with the exact authenticators, browsers, and policies you support before production use.

Best Practices

Security Considerations

Secure backup-code storage: Ask users to print codes for safe storage or place them in a password manager. Never share or post them online.
Rate limiting: The platform enforces rate limits on MFA verification attempts. Treat 429 as a cooldown, not a reason to retry rapidly.
Pre-authentication token expiration: Pre-authentication tokens expire after five minutes and must not be accepted as full application sessions.
Backup-code regeneration: Warn users that regeneration invalidates all previous codes.
Account recovery: Define a recovery process for users who lose both the authenticator and backup codes. Verify identity independently before an administrator disables MFA.
Secret handling: Never record TOTP secrets, QR payloads, verification codes, pre-authentication tokens, or backup codes in logs or analytics.

UX Considerations

Provide clear, step-by-step setup instructions.
Always offer manual entry as an alternative to the QR code.
Require users to acknowledge and save backup codes during setup.
Handle errors without discarding valid progress or exposing sensitive state.
Test every normal and recovery flow before production.

Implementation Checklist

Check MFA status before showing enable or disable options.
Display the QR code clearly with a manual-entry alternative.
Require verification before enabling MFA.
Require users to acknowledge backup codes.
Provide backup-code download and copy options.
Handle both TOTP codes and backup codes during login.
Implement backup-code regeneration with an invalidation warning.
Add confirmation for MFA disablement.
Test expired pre-authentication tokens and rate limits.
Test full recovery scenarios and document the support process.
Verify supported authenticator applications rather than treating the illustrative app list as a compatibility guarantee.

Error Handling

import { SsoApiError } from '@drmhse/sso-sdk';

async function handleMfaError(error: unknown): Promise<string> {
  if (error instanceof SsoApiError) {
    switch (error.statusCode) {
      case 400:
        if (error.message.includes('already enabled')) {
          return 'MFA is already enabled for this account';
        }
        return 'Invalid MFA code format or setup not initiated';
      case 401:
        return 'Invalid or expired code. Please try again.';
      case 429:
        return 'Too many attempts. Please try again later.';
      case 500:
        return 'Server error. Please try again later.';
      default:
        return error.message;
    }
  }
  return 'An unexpected error occurred';
}

try {
  await sso.user.mfa.verify(code);
} catch (error) {
  const message = await handleMfaError(error);
  showErrorToUser(message);
}

Do not expose raw server details in user-facing errors. Preserve the underlying error only in telemetry that has already removed secrets and tokens.