MFA Troubleshooting and Security

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

1. 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.
2. Rate limiting: The platform enforces rate limits on MFA verification attempts. Treat 429 as a cooldown, not a reason to retry rapidly.
3. Pre-authentication token expiration: Pre-authentication tokens expire after five minutes and must not be accepted as full application sessions.
4. Backup-code regeneration: Warn users that regeneration invalidates all previous codes.
5. Account recovery: Define a recovery process for users who lose both the authenticator and backup codes. Verify identity independently before an administrator disables MFA.
6. Secret handling: Never record TOTP secrets, QR payloads, verification codes, pre-authentication tokens, or backup codes in logs or analytics.

UX Considerations

1. Provide clear, step-by-step setup instructions.
2. Always offer manual entry as an alternative to the QR code.
3. Require users to acknowledge and save backup codes during setup.
4. Handle errors without discarding valid progress or exposing sensitive state.
5. 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.

Common failures

Production qualification

• Exercise enrollment with every authenticator application you claim to support, including manual entry.
• Verify TOTP and backup-code login, code reuse rejection, and token expiration.
• Verify backup-code regeneration invalidates the old set.
• Verify self-service and administrator disablement invalidate the factor and follow session-revocation policy.
• Confirm keyboard, screen-reader, mobile, and error-state behavior in the UI integration.
• Confirm recovery actions are auditable and support staff cannot bypass the identity-verification policy.

For endpoint-level behavior, see the MFA API reference and SDK user reference.