MFA UI Integration

Compose AuthOS MFA enrollment, backup-code, and disable controls into an account-security page

AuthOS release 0.8.2 TypeScript SDK 0.8.0 Latest-only documentation
Updated Jul 15, 2026 Edit this page
On this page

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

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.

Complete MFA Settings Page

This page checks status once, shows enrollment only when MFA is disabled, and exposes recovery-code and disable controls only after enablement.

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

interface MfaSettingsPageProps {
  sso: SsoClient;
}

export function MfaSettingsPage({ sso }: MfaSettingsPageProps) {
  const [mfaEnabled, setMfaEnabled] = useState<boolean | null>(null);
  const [loading, setLoading] = useState(true);
  const [showSetup, setShowSetup] = useState(false);

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

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

  const handleSetupComplete = () => {
    setShowSetup(false);
    setMfaEnabled(true);
  };

  const handleDisabled = () => {
    setMfaEnabled(false);
  };

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

  return (
    <div className="mfa-settings-page">
      <h1>Two-Factor Authentication</h1>

      {mfaEnabled === false && !showSetup && (
        <div className="mfa-disabled-state">
          <div className="info-card">
            <h2>Protect Your Account</h2>
            <p>
              Two-factor authentication adds an extra layer of security to your
              account by requiring both your password and a verification code
              from your phone.
            </p>
            <button onClick={() => setShowSetup(true)} className="primary">
              Enable Two-Factor Authentication
            </button>
          </div>
        </div>
      )}

      {mfaEnabled === false && showSetup && (
        <MfaSetupFlow sso={sso} onComplete={handleSetupComplete} />
      )}

      {mfaEnabled === true && (
        <div className="mfa-enabled-state">
          <div className="status-card success">
            <h2>Two-Factor Authentication is Enabled</h2>
            <p>Your account is protected with 2FA</p>
          </div>
          <div className="mfa-management">
            <BackupCodesManager sso={sso} />
            <DisableMfa sso={sso} onDisabled={handleDisabled} />
          </div>
        </div>
      )}
    </div>
  );
}

The documentation template supplies the page H1; the <h1> in this application component is correct only when the component is the main account-security view. If it is nested under another application heading, demote it to preserve one H1 and a logical heading hierarchy.

Integration behavior

  • Move focus to the first field when a user starts enrollment or reaches an MFA login challenge.
  • Announce loading and error states without moving users away from their task.
  • Require confirmation before invalidating backup codes or disabling MFA.
  • Provide manual TOTP-secret entry and both copy and download recovery-code actions.
  • Clear secrets, codes, and pre-authentication tokens when the user cancels, completes, or times out.
  • Re-read server status after a mutation instead of trusting stale UI state.

Review Troubleshooting and security before production rollout.