docker / docker/docs

[docs-scanner] 2FA account recovery instructions contain logical contradiction

Open Beginner friendly
#26,084 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Markdown
Stars
4.7k
Forks
8.5k
Avg merge
2d 18h
Merged PRs (30d)
108

Description

File: content/manuals/security/authentication/2fa/recover-hub-account.md

Issue

The "Recover your account without access" section instructs users to sign in with username and password when they've lost both their 2FA device and recovery code:

If you lost access to both your two-factor authentication application and your recovery code:

  1. Sign in to your Docker account with your username and password.
  2. Select I've lost my authentication device and I've lost my recovery code.
Why this matters

This is a logical contradiction that will confuse users in a critical account recovery situation. When 2FA is enabled on an account, signing in requires:

  1. Username and password
  2. The 2FA code from the authenticator app

If a user has lost their authentication device, they cannot provide the 2FA code, which means they cannot complete step 1 (signing in). The instructions don't explain how to bypass the 2FA prompt or access the "I've lost my authentication device" option without being able to sign in first.

A user following these instructions will be stuck at the sign-in page, unable to proceed to step 2 where they can indicate they've lost their device.

Suggested fix

Clarify the actual recovery flow. Possible approaches:

  1. If there's a "lost device" link on the sign-in page itself (before completing authentication), explain that:

    • Go to the sign-in page
    • Enter username and password
    • When prompted for 2FA code, select "I've lost my authentication device"
    • Then select "I've lost my recovery code"
  2. If users must contact support without being able to sign in at all, simplify to:

    • If you've lost both your authentication device and recovery code, you cannot sign in
    • Complete the Contact Support form with your primary email address for recovery instructions

The instructions should match the actual user experience when 2FA blocks sign-in.


Found by nightly documentation quality scanner

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Open content/manuals/security/authentication/2fa/recover-hub-account.md and inspect the current "Recover your account without access" section. Verify the actual Docker sign-in and 2FA recovery flow, including whether the lost-device option appears before or after authentication and whether the Contact Support form is required. Done means the instructions match the user experience without presenting contradictory steps.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker
Domain
authentication, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.