Make acknowledging 2FA authenticator recovery methods mandatory during 2FA setup

Background

Currently, users can enable 2FA without having to set up their authenticator app's own backup/recovery system. This leads to increase in support tickets when users lose access to their authenticator apps and cannot self recover their accounts. As the user's might not be aware of the different self-serve options available to them, this issue is aimed towards implementing mandatory steps for user's to acknowledge the different options available to them.

Objective

Implement mandatory steps in the 2FA setup flow that require users to:

  1. Acknowledge they have saved their GitLab recovery codes.
  2. Acknowledge they have enabled/understood their authenticator app's own recovery method (cloud backup, secret keys, etc.).
  3. Acknowledge they are aware that recovery codes can be regenerated via SSH keys.

Proposed Solution

  • Once the user hits register when enabling 2FA, the users will be taken the download code page (already exists).
  • Add three mandatory confirmation messages in the 2FA setup workflow:
    • Step 1: Require users to explicitly confirm they have backed up their GitLab recovery codes (remove copy button).
    • Step 2: Require users to confirm they have read the documentation about their authenticator's backup method (e.g., cloud backup for Google/Microsoft Authenticator, secret keys for 1Password, etc.).
    • Step 3: Require users to confirm they are aware that recovery codes can be regenerated via SSH keys.
  • These steps should be blocking - users cannot complete 2FA setup without these confirmations
  • Link the documentation related to each method.

Alternatives

  • Leave the 2FA process as it is currently with the recovery code download page.

Related Work

  • Epic: &349
  • Informed by authenticator testing research
  • Complements Zendesk bot improvements and documentation updates

Timeline

Feature request to be submitted after deadline for comments is passed.

Notes

  • This acknowledgment approach provides three layers of recovery protection
  • Reduces dependency on GitLab support for authenticator-specific recovery issues
  • Aligns with goal of improving self-service recovery options
Edited by Tooba Sheikh