From afd6e3c6372de79f19081fde93ae85c034b6a5c3 Mon Sep 17 00:00:00 2001 From: Alexa Date: Wed, 30 Sep 2026 13:53:54 -0500 Subject: [PATCH 1/5] security: refresh 2FA pages for accuracy and structure The 2FA pages described the recovery code as a reusable backup and left out the lost-device sign-in path, the verified-email and enforced-SSO conditions, and the exact control names on the settings screens. Add a callout that the recovery code works once and turns 2FA off, add the "Sign in with your recovery code" steps, name the Copy, Download, Print, QR Code, and Text Code controls, scope the authenticator prompt to password sign-in, shorten the benefits list, and add next steps. Co-authored-by: Cursor --- .../security/authentication/2fa/_index.md | 83 ++++++++++++------- .../authentication/2fa/recover-hub-account.md | 67 +++++++++++---- 2 files changed, 103 insertions(+), 47 deletions(-) diff --git a/content/manuals/security/authentication/2fa/_index.md b/content/manuals/security/authentication/2fa/_index.md index d438674ad0c..bf6f48ae9f8 100644 --- a/content/manuals/security/authentication/2fa/_index.md +++ b/content/manuals/security/authentication/2fa/_index.md @@ -17,34 +17,44 @@ aliases: {{< summary-bar feature_name="2FA" >}} -Two-factor authentication (2FA) adds a security layer to your Docker account by -requiring a unique security code in addition to your password when signing in. -This prevents unauthorized access even if your password is compromised. +Two-factor authentication (2FA) adds a second step to password sign-in. After +you enter your password, Docker asks for a code from an authenticator app. If +someone learns your password, they still can't sign in without the code. -When you turn on two-factor authentication, Docker provides a unique recovery -code specific to your account. Store this code securely as it lets you recover -your account if you lose access to your authenticator app. +When you turn on 2FA, Docker gives you a recovery code for your account. The +recovery code is how you get back in if you lose your authenticator app, so +store it somewhere safe. -## Key benefits +> [!IMPORTANT] +> +> The recovery code works once. Using it signs you in and turns 2FA off. If +> you lose both your authenticator app and your recovery code, you need to +> contact Docker Support to recover your account. -Two-factor authentication improves your account security: +## Key benefits -- Protection against password breaches: Even if your password is stolen or - leaked, attackers can't access your account without your second factor. -- Secure CLI access: Required for Docker CLI authentication when 2FA is turned - on, ensuring automated tools use personal access tokens instead of passwords. -- Compliance requirements: Many organizations require 2FA for accessing - development and production resources. -- Peace of mind: Know that your Docker repositories, images, and account - settings are protected by industry-standard security practices. +- Protection against stolen passwords: An attacker who has your password + still needs the code from your authenticator app. +- Secure CLI access: When 2FA is on, the Docker CLI needs a personal access + token instead of your password, so scripts and CI never hold your password. +- Compliance: Many organizations require 2FA for access to development and + production resources. ## Prerequisites -Before turning on two-factor authentication, you need: +Before you turn on 2FA, you need: -- A smartphone or device with a time-based one-time password (TOTP) - authenticator app installed -- Access to your Docker account password +- A time-based one-time password (TOTP) authenticator app on your phone or + another device +- Your Docker account password +- A verified email address on your account. If your email isn't verified, + Docker asks you to verify it before you can open the 2FA settings. + +> [!NOTE] +> +> If your organization enforces single sign-on (SSO), the **2FA** page shows +> a message to contact your administrator instead. Your identity provider +> manages authentication for your account. ## Enable two-factor authentication @@ -55,23 +65,29 @@ To turn on 2FA for your Docker account: settings**. 1. Select **2FA**. 1. Enter your account password, then select **Confirm**. -1. Save your recovery code and store it somewhere safe. You can use your - recovery code to recover your account in the event you lose access to your - authenticator app. -1. Use a TOTP mobile app to scan the QR code or enter the text code. -1. Once you've linked your authenticator app, enter the six-digit code in the - text field. +1. Save your recovery code. Select **Copy**, or open the menu next to it to + **Download** or **Print** the code. Store it somewhere safe. +1. Open your authenticator app and either scan the code on the **QR Code** + tab or enter the code from the **Text Code** tab. +1. Enter the six-digit code from your authenticator app in the + **Authentication code** field. 1. Select **Enable 2FA**. -Two-factor authentication is now active on your account. You'll need to enter a -security code from your authenticator app each time you sign in. +Two-factor authentication is on. From now on, when you sign in with your +password, Docker asks for a code from your authenticator app. + +To sign in from the Docker CLI, use a +[personal access token](/manuals/security/access-tokens/personal-access-tokens.md) +in place of your password. ## Disable two-factor authentication > [!WARNING] > -> Disabling two-factor authentication results in decreased security for your -> Docker account. +> Turning off 2FA leaves your account protected by your password alone. + +To switch to a new device, turn off 2FA and then turn it on again from the +new device. 1. Sign in to your [Docker account](https://app.docker.com/login). 1. Select your avatar and then from the drop-down menu, select **Account @@ -79,3 +95,10 @@ security code from your authenticator app each time you sign in. 1. Select **2FA**. 1. Enter your password, then select **Confirm**. 1. Select **Disable 2FA**. + +## Next steps + +- [Recover your account](/manuals/security/authentication/2fa/recover-hub-account.md) + if you lose your authenticator app or recovery code. +- [Create a personal access token](/manuals/security/access-tokens/personal-access-tokens.md) + for CLI sign-in and automation. diff --git a/content/manuals/security/authentication/2fa/recover-hub-account.md b/content/manuals/security/authentication/2fa/recover-hub-account.md index dcf6cd19c81..5d97c6f77c8 100644 --- a/content/manuals/security/authentication/2fa/recover-hub-account.md +++ b/content/manuals/security/authentication/2fa/recover-hub-account.md @@ -16,32 +16,65 @@ weight: 20 {{< summary-bar feature_name="2FA" >}} -If you lose your two-factor authentication recovery code, or lose access to both -your authenticator app and your recovery code, you can generate a new code or -contact Support to recover your account. +This page explains how to get back into your Docker account when part of +your two-factor authentication (2FA) setup is missing. What you do depends +on what you still have: + +- Lost your recovery code but can still sign in: + [Generate a new recovery code](#generate-a-new-recovery-code). +- Lost your authenticator app but have your recovery code: + [Sign in with your recovery code](#sign-in-with-your-recovery-code). +- Lost both: + [Contact Docker Support](#recover-your-account-without-access). ## Generate a new recovery code -If you lost your two-factor authentication recovery code but still have access -to your Docker Hub account, you can generate a new recovery code. +If you lost your recovery code but can still sign in, generate a new one. +The new code replaces the old one, which stops working. -1. Sign in to your [Docker account](https://app.docker.com/login) with your - username and password. -1. Select your avatar and from the drop-down menu, select **Account settings**. +1. Sign in to your [Docker account](https://app.docker.com/login). Enter + your password, then the code from your authenticator app. +1. Select your avatar and from the drop-down menu, select **Account + settings**. 1. Select **2FA**. 1. Enter your password, then select **Confirm**. 1. Select **Generate new code**. -This generates a new code. Select the visibility icon to view the code. Save -your recovery code and store it somewhere safe. +Select the visibility icon to view the new code, then **Copy**, **Download**, +or **Print** it. Store it somewhere safe. + +## Sign in with your recovery code + +If you lost your authenticator app but still have your recovery code, use +the code to sign in. + +> [!IMPORTANT] +> +> The recovery code works once. Using it signs you in and turns 2FA off. Turn +> 2FA on again from your new device as soon as you're signed in. + +1. Sign in to your [Docker account](https://app.docker.com/login) with your + username and password. +1. On the **Two-Factor Authentication** page, select **I've lost my + authentication device**. +1. Enter your recovery code, then select **Verify**. + +You're signed in and 2FA is off. To protect your account again, follow +[Enable two-factor authentication](/manuals/security/authentication/2fa/_index.md#enable-two-factor-authentication). ## Recover your account without access -If you lost access to both your two-factor authentication application and your -recovery code, you can't complete the normal sign-in process because you don't -have the required 2FA verification code. +If you lost both your authenticator app and your recovery code, you can't +complete sign-in on your own. + +Open the +[Contact Support form](https://hub.docker.com/support/contact/?category=2fa-lockout). +The form is prefilled for a 2FA lockout. Enter the email address on your +Docker account and follow the instructions from Docker Support. + +## Next steps -Complete the -[Contact Support form](https://hub.docker.com/support/contact/?category=2fa-lockout) -with the primary email address associated with your Docker ID and follow the -recovery instructions provided by Docker Support. +- [Enable two-factor authentication](/manuals/security/authentication/2fa/_index.md) + again after you recover your account. +- [Create a personal access token](/manuals/security/access-tokens/personal-access-tokens.md) + for CLI sign-in and automation. From e12d1f5136d060bf05f508c6a6e169351f3dcfe6 Mon Sep 17 00:00:00 2001 From: Alexa Date: Wed, 30 Sep 2026 13:54:12 -0500 Subject: [PATCH 2/5] security: align 2FA pages with the style guide The refreshed 2FA pages still used label-and-colon bullets, negative contractions, generic titles and keywords, and inline links that pushed lines past 80 characters. Remove the Key benefits list, rewrite negative contractions, match the avatar navigation wording used elsewhere, sharpen the page titles, descriptions, and keywords for search, rename the Support section, and move long links to reference definitions. Co-authored-by: Cursor --- .../security/authentication/2fa/_index.md | 87 +++++++++---------- .../authentication/2fa/recover-hub-account.md | 63 +++++++------- 2 files changed, 73 insertions(+), 77 deletions(-) diff --git a/content/manuals/security/authentication/2fa/_index.md b/content/manuals/security/authentication/2fa/_index.md index bf6f48ae9f8..c2a7e6936a9 100644 --- a/content/manuals/security/authentication/2fa/_index.md +++ b/content/manuals/security/authentication/2fa/_index.md @@ -2,10 +2,11 @@ title: Enable two-factor authentication for your Docker account linkTitle: Two-factor authentication description: >- - Enable or disable two-factor authentication on your Docker account for - enhanced security and account protection. -keywords: two-factor authentication, 2FA, docker hub security, - account security, TOTP, authenticator app, disable 2FA, recovery code + Turn on two-factor authentication for your Docker account, save the + recovery code, or turn 2FA off. +keywords: two-factor authentication, 2FA, Docker account, TOTP, + authenticator app, recovery code, QR code, personal access token, + disable 2FA, Docker Hub weight: 20 aliases: - /docker-hub/2fa/ @@ -17,28 +18,18 @@ aliases: {{< summary-bar feature_name="2FA" >}} -Two-factor authentication (2FA) adds a second step to password sign-in. After -you enter your password, Docker asks for a code from an authenticator app. If -someone learns your password, they still can't sign in without the code. +Two-factor authentication (2FA) adds a code from an authenticator app after +you sign in with your password. Someone who knows your password still needs +that code to sign in. -When you turn on 2FA, Docker gives you a recovery code for your account. The -recovery code is how you get back in if you lose your authenticator app, so -store it somewhere safe. +When you turn on 2FA, Docker gives you a recovery code. Keep it somewhere +safe. You use it to get back in if you lose your authenticator app. > [!IMPORTANT] > -> The recovery code works once. Using it signs you in and turns 2FA off. If -> you lose both your authenticator app and your recovery code, you need to -> contact Docker Support to recover your account. - -## Key benefits - -- Protection against stolen passwords: An attacker who has your password - still needs the code from your authenticator app. -- Secure CLI access: When 2FA is on, the Docker CLI needs a personal access - token instead of your password, so scripts and CI never hold your password. -- Compliance: Many organizations require 2FA for access to development and - production resources. +> The recovery code works once. Using it signs you in and turns 2FA off. +> If you lose both your authenticator app and your recovery code, contact +> Docker Support to recover your account. ## Prerequisites @@ -47,38 +38,38 @@ Before you turn on 2FA, you need: - A time-based one-time password (TOTP) authenticator app on your phone or another device - Your Docker account password -- A verified email address on your account. If your email isn't verified, - Docker asks you to verify it before you can open the 2FA settings. +- A verified email address on your account + +Docker opens the 2FA settings after your email address is verified. > [!NOTE] > -> If your organization enforces single sign-on (SSO), the **2FA** page shows -> a message to contact your administrator instead. Your identity provider -> manages authentication for your account. +> If your organization enforces single sign-on (SSO), the **2FA** page +> tells you to contact your administrator. Your identity provider manages +> sign-in for your account. ## Enable two-factor authentication To turn on 2FA for your Docker account: 1. Sign in to your [Docker account](https://app.docker.com/login). -1. Select your avatar and then from the drop-down menu, select **Account +1. Select your avatar in the top-right corner, then select **Account settings**. 1. Select **2FA**. 1. Enter your account password, then select **Confirm**. -1. Save your recovery code. Select **Copy**, or open the menu next to it to - **Download** or **Print** the code. Store it somewhere safe. -1. Open your authenticator app and either scan the code on the **QR Code** - tab or enter the code from the **Text Code** tab. -1. Enter the six-digit code from your authenticator app in the - **Authentication code** field. +1. Save your recovery code. Select **Copy**, or open the menu next to + **Copy** and select **Download** or **Print**. +1. Open your authenticator app. Scan the code on the **QR Code** tab, or + enter the code from the **Text Code** tab. +1. Enter the six-digit code from your authenticator app in + **Authentication code**. 1. Select **Enable 2FA**. -Two-factor authentication is on. From now on, when you sign in with your -password, Docker asks for a code from your authenticator app. +Two-factor authentication is on. When you sign in with your password, +Docker asks for a code from your authenticator app. -To sign in from the Docker CLI, use a -[personal access token](/manuals/security/access-tokens/personal-access-tokens.md) -in place of your password. +To sign in from the Docker CLI, use a [personal access token][pat] in +place of your password. ## Disable two-factor authentication @@ -86,19 +77,21 @@ in place of your password. > > Turning off 2FA leaves your account protected by your password alone. -To switch to a new device, turn off 2FA and then turn it on again from the -new device. - 1. Sign in to your [Docker account](https://app.docker.com/login). -1. Select your avatar and then from the drop-down menu, select **Account +1. Select your avatar in the top-right corner, then select **Account settings**. 1. Select **2FA**. 1. Enter your password, then select **Confirm**. 1. Select **Disable 2FA**. +To move 2FA to a new device, turn it off, then turn it on again from that +device. + ## Next steps -- [Recover your account](/manuals/security/authentication/2fa/recover-hub-account.md) - if you lose your authenticator app or recovery code. -- [Create a personal access token](/manuals/security/access-tokens/personal-access-tokens.md) - for CLI sign-in and automation. +- [Recover your account][recover] if you lose your authenticator app or + recovery code. +- Create a [personal access token][pat] for the Docker CLI and automation. + +[pat]: /manuals/security/access-tokens/personal-access-tokens.md +[recover]: /manuals/security/authentication/2fa/recover-hub-account.md diff --git a/content/manuals/security/authentication/2fa/recover-hub-account.md b/content/manuals/security/authentication/2fa/recover-hub-account.md index 5d97c6f77c8..0f31a5e60bc 100644 --- a/content/manuals/security/authentication/2fa/recover-hub-account.md +++ b/content/manuals/security/authentication/2fa/recover-hub-account.md @@ -1,11 +1,12 @@ --- -title: Recover your Docker account +title: Recover your Docker account and two-factor recovery code linkTitle: Recover your account description: >- - Recover your Docker account and manage two-factor authentication recovery - codes. + Sign in with a recovery code, generate a new recovery code, or contact + Support when you lose your authenticator app. keywords: account recovery, two-factor authentication, 2FA, recovery code, - docker hub security, lost authenticator app, 2FA lockout + lost authenticator app, 2FA lockout, Docker account, generate recovery + code aliases: - /docker-hub/2fa/recover-hub-account/ - /security/for-developers/2fa/recover-hub-account/ @@ -16,42 +17,42 @@ weight: 20 {{< summary-bar feature_name="2FA" >}} -This page explains how to get back into your Docker account when part of -your two-factor authentication (2FA) setup is missing. What you do depends -on what you still have: +Get back into your Docker account when part of your two-factor +authentication (2FA) setup is missing. What you do depends on what you +still have: -- Lost your recovery code but can still sign in: +- You lost your recovery code and can still sign in. [Generate a new recovery code](#generate-a-new-recovery-code). -- Lost your authenticator app but have your recovery code: +- You lost your authenticator app and still have your recovery code. [Sign in with your recovery code](#sign-in-with-your-recovery-code). -- Lost both: - [Contact Docker Support](#recover-your-account-without-access). +- You lost both your authenticator app and your recovery code. + [Contact Docker Support](#contact-docker-support). ## Generate a new recovery code -If you lost your recovery code but can still sign in, generate a new one. -The new code replaces the old one, which stops working. +If you lost your recovery code and can still sign in, generate a new one. +The new code replaces the previous code. 1. Sign in to your [Docker account](https://app.docker.com/login). Enter your password, then the code from your authenticator app. -1. Select your avatar and from the drop-down menu, select **Account +1. Select your avatar in the top-right corner, then select **Account settings**. 1. Select **2FA**. 1. Enter your password, then select **Confirm**. 1. Select **Generate new code**. -Select the visibility icon to view the new code, then **Copy**, **Download**, -or **Print** it. Store it somewhere safe. +Select the visibility icon to view the new code. Then select **Copy**, +**Download**, or **Print**, and store the code somewhere safe. ## Sign in with your recovery code -If you lost your authenticator app but still have your recovery code, use +If you lost your authenticator app and still have your recovery code, use the code to sign in. > [!IMPORTANT] > -> The recovery code works once. Using it signs you in and turns 2FA off. Turn -> 2FA on again from your new device as soon as you're signed in. +> The recovery code works once. Using it signs you in and turns 2FA off. +> Turn 2FA on again from your new device as soon as you're signed in. 1. Sign in to your [Docker account](https://app.docker.com/login) with your username and password. @@ -60,21 +61,23 @@ the code to sign in. 1. Enter your recovery code, then select **Verify**. You're signed in and 2FA is off. To protect your account again, follow -[Enable two-factor authentication](/manuals/security/authentication/2fa/_index.md#enable-two-factor-authentication). +[Turn on 2FA][enable]. -## Recover your account without access +## Contact Docker Support -If you lost both your authenticator app and your recovery code, you can't -complete sign-in on your own. +If you lose both your authenticator app and your recovery code, contact +Docker Support to restore access. Open the -[Contact Support form](https://hub.docker.com/support/contact/?category=2fa-lockout). -The form is prefilled for a 2FA lockout. Enter the email address on your -Docker account and follow the instructions from Docker Support. +[Contact Support](https://hub.docker.com/support/contact/?category=2fa-lockout). +The subject and description already describe a 2FA lockout. Enter the +email address on your Docker account, then follow the instructions from +Docker Support. ## Next steps -- [Enable two-factor authentication](/manuals/security/authentication/2fa/_index.md) - again after you recover your account. -- [Create a personal access token](/manuals/security/access-tokens/personal-access-tokens.md) - for CLI sign-in and automation. +- [Turn on 2FA][enable] again after you recover your account. +- Create a [personal access token][pat] for the Docker CLI and automation. + +[enable]: /manuals/security/authentication/2fa/_index.md +[pat]: /manuals/security/access-tokens/personal-access-tokens.md From 8b3996b603452ce8a85145d0dd0c9722ba2d3937 Mon Sep 17 00:00:00 2001 From: Alexa Date: Wed, 30 Sep 2026 14:30:25 -0500 Subject: [PATCH 3/5] security: split 2FA into an overview and a manage page The 2FA section page was a procedure: after two sentences it went into prerequisites, enable steps, and disable steps, and it left out how the second factor is asked for, when the CLI needs a personal access token, and what the recovery code does. Move the prerequisites, enable, and disable steps to a new manage.md and add a section for moving 2FA to a new device. Rewrite _index.md as an overview that explains the TOTP pairing and sign-in prompt, lists when Docker asks for the code, and describes the single-use recovery code and the emails Docker sends. Move the disable-2fa aliases to manage.md and point the "enable" links from the accounts pages and the recovery page at the new manage page. Co-authored-by: Cursor --- content/manuals/accounts/individual/_index.md | 2 +- .../accounts/individual/create-account.md | 2 +- .../accounts/individual/manage-account.md | 4 +- .../security/authentication/2fa/_index.md | 132 +++++++++--------- .../security/authentication/2fa/manage.md | 102 ++++++++++++++ .../authentication/2fa/recover-hub-account.md | 2 +- 6 files changed, 171 insertions(+), 73 deletions(-) create mode 100644 content/manuals/security/authentication/2fa/manage.md diff --git a/content/manuals/accounts/individual/_index.md b/content/manuals/accounts/individual/_index.md index ad0cf10392c..2bc9ddc59a2 100644 --- a/content/manuals/accounts/individual/_index.md +++ b/content/manuals/accounts/individual/_index.md @@ -23,7 +23,7 @@ grid: link: /security/access-tokens/ - title: Set up two-factor authentication description: Add an extra layer of authentication to your Docker account. - link: /security/2fa/ + link: /security/authentication/2fa/manage/ icon: device-phone-mobile - title: Organization accounts description: Learn how to create and manage Docker organizations. diff --git a/content/manuals/accounts/individual/create-account.md b/content/manuals/accounts/individual/create-account.md index 3db92002274..766a75f8912 100644 --- a/content/manuals/accounts/individual/create-account.md +++ b/content/manuals/accounts/individual/create-account.md @@ -87,4 +87,4 @@ basis: ## Next steps - [Manage a Docker account](/manuals/accounts/individual/manage-account.md) -- [Enable two-factor authentication](/manuals/security/authentication/2fa/_index.md) +- [Enable two-factor authentication](/manuals/security/authentication/2fa/manage.md) diff --git a/content/manuals/accounts/individual/manage-account.md b/content/manuals/accounts/individual/manage-account.md index 616abe7bfac..a841bdbb1f4 100644 --- a/content/manuals/accounts/individual/manage-account.md +++ b/content/manuals/accounts/individual/manage-account.md @@ -79,7 +79,7 @@ To update your two-factor authentication (2FA) settings: 1. Select **2FA**. For more information, see -[Enable two-factor authentication](/manuals/security/authentication/2fa/_index.md). +[Enable two-factor authentication](/manuals/security/authentication/2fa/manage.md). ## Manage personal access tokens @@ -129,4 +129,4 @@ For information on deactivating your account, see - [Docker individual accounts overview](/manuals/accounts/individual/_index.md) - [Create a Docker account](/manuals/accounts/individual/create-account.md) -- [Enable two-factor authentication](/manuals/security/authentication/2fa/_index.md) +- [Enable two-factor authentication](/manuals/security/authentication/2fa/manage.md) diff --git a/content/manuals/security/authentication/2fa/_index.md b/content/manuals/security/authentication/2fa/_index.md index c2a7e6936a9..4585fcd3c6e 100644 --- a/content/manuals/security/authentication/2fa/_index.md +++ b/content/manuals/security/authentication/2fa/_index.md @@ -1,97 +1,93 @@ --- -title: Enable two-factor authentication for your Docker account +title: Two-factor authentication for your Docker account linkTitle: Two-factor authentication description: >- - Turn on two-factor authentication for your Docker account, save the - recovery code, or turn 2FA off. -keywords: two-factor authentication, 2FA, Docker account, TOTP, - authenticator app, recovery code, QR code, personal access token, - disable 2FA, Docker Hub + Learn how two-factor authentication protects a Docker account, when Docker + asks for the code, and what the recovery code does. +keywords: two-factor authentication, 2FA, how 2FA works, Docker account, + TOTP, authenticator app, authentication code, recovery code, personal + access token, docker login, account security, Docker Hub weight: 20 aliases: - /docker-hub/2fa/ - - /security/2fa/disable-2fa/ - /security/for-developers/2fa/ - - /security/for-developers/2fa/disable-2fa/ - /security/2fa/ +grid: + - title: Turn 2FA on or off + description: >- + Set up an authenticator app, save the recovery code, or turn 2FA off. + icon: device-phone-mobile + link: /security/authentication/2fa/manage/ + - title: Recover your account + description: >- + Sign in with a recovery code, generate a new one, or contact Support. + icon: key + link: /security/authentication/2fa/recover-hub-account/ --- {{< summary-bar feature_name="2FA" >}} -Two-factor authentication (2FA) adds a code from an authenticator app after -you sign in with your password. Someone who knows your password still needs -that code to sign in. +Two-factor authentication (2FA) adds a code from an authenticator app to +your password when you sign in to your Docker account. Someone who knows +your password still needs the code from your device to sign in. -When you turn on 2FA, Docker gives you a recovery code. Keep it somewhere -safe. You use it to get back in if you lose your authenticator app. +2FA is a setting on individual Docker accounts. You turn it on and off +yourself in **Account settings**. Organization and company settings do not +include 2FA. To control how members sign in across an organization, use +[single sign-on](/manuals/security/authentication/single-sign-on/_index.md). -> [!IMPORTANT] -> -> The recovery code works once. Using it signs you in and turns 2FA off. -> If you lose both your authenticator app and your recovery code, contact -> Docker Support to recover your account. - -## Prerequisites - -Before you turn on 2FA, you need: +## How two-factor authentication works -- A time-based one-time password (TOTP) authenticator app on your phone or - another device -- Your Docker account password -- A verified email address on your account +When you turn on 2FA, you pair a time-based one-time password (TOTP) +authenticator app with your account by scanning a QR code or entering a +text code. Any authenticator app that supports TOTP works. The app then +shows a six-digit code that changes every 30 seconds. -Docker opens the 2FA settings after your email address is verified. +After you enter your password, Docker shows the **Two-Factor +Authentication** page. Enter the code from your app in +**Authentication Code** and select **Verify**. If you no longer have the +device, select **I've lost my authentication device** to sign in with +your recovery code instead. -> [!NOTE] -> -> If your organization enforces single sign-on (SSO), the **2FA** page -> tells you to contact your administrator. Your identity provider manages -> sign-in for your account. - -## Enable two-factor authentication +A wrong code fails with `Invalid one-time password`. After repeated +failures, Docker returns `Too many failed login attempts` and blocks +further attempts for a short time. -To turn on 2FA for your Docker account: +Docker keeps one authenticator per account. To move 2FA to a new device, +turn it off and turn it on again from the new device. -1. Sign in to your [Docker account](https://app.docker.com/login). -1. Select your avatar in the top-right corner, then select **Account - settings**. -1. Select **2FA**. -1. Enter your account password, then select **Confirm**. -1. Save your recovery code. Select **Copy**, or open the menu next to - **Copy** and select **Download** or **Print**. -1. Open your authenticator app. Scan the code on the **QR Code** tab, or - enter the code from the **Text Code** tab. -1. Enter the six-digit code from your authenticator app in - **Authentication code**. -1. Select **Enable 2FA**. +## When Docker asks for the code -Two-factor authentication is on. When you sign in with your password, -Docker asks for a code from your authenticator app. +| Sign-in | What Docker asks for | +| --- | --- | +| Browser sign-in to Docker Home or Docker Hub | Your password, then the code from your authenticator app | +| `docker login` with no username | The same browser sign-in, if the browser is not already signed in | +| `docker login -u`, scripts, and CI | A [personal access token](/manuals/security/access-tokens/personal-access-tokens.md) in the password prompt. Password sign-in from the CLI is not supported when 2FA is on | +| Enforced single sign-on | No code. Your identity provider handles sign-in, and the **2FA** page tells you to contact your administrator | -To sign in from the Docker CLI, use a [personal access token][pat] in -place of your password. +## Recovery code -## Disable two-factor authentication +Docker gives you one recovery code when you turn on 2FA. The code signs +you in if you lose your authenticator app, so copy, download, or print it +and store it somewhere safe. -> [!WARNING] +> [!IMPORTANT] > -> Turning off 2FA leaves your account protected by your password alone. +> The recovery code works once. Using it on the **Lost Authentication +> Device** page signs you in, turns 2FA off, and deletes the code. Turn +> 2FA on again from your new device as soon as you are signed in. -1. Sign in to your [Docker account](https://app.docker.com/login). -1. Select your avatar in the top-right corner, then select **Account - settings**. -1. Select **2FA**. -1. Enter your password, then select **Confirm**. -1. Select **Disable 2FA**. +- **Generate new code** replaces the previous code. Only the latest code + works. +- Docker asks for your password before it shows the code or lets you + change 2FA settings. +- If you lose both the authenticator app and the recovery code, contact + Docker Support to recover your account. -To move 2FA to a new device, turn it off, then turn it on again from that -device. +Docker emails the verified address on your account when you turn 2FA on +or off, when a recovery code is generated, and when a recovery code is +used to sign in. The email does not contain the code. ## Next steps -- [Recover your account][recover] if you lose your authenticator app or - recovery code. -- Create a [personal access token][pat] for the Docker CLI and automation. - -[pat]: /manuals/security/access-tokens/personal-access-tokens.md -[recover]: /manuals/security/authentication/2fa/recover-hub-account.md +{{< grid >}} diff --git a/content/manuals/security/authentication/2fa/manage.md b/content/manuals/security/authentication/2fa/manage.md new file mode 100644 index 00000000000..c0c62c04f58 --- /dev/null +++ b/content/manuals/security/authentication/2fa/manage.md @@ -0,0 +1,102 @@ +--- +title: Manage two-factor authentication for your Docker account +linkTitle: Manage +description: >- + Turn on two-factor authentication for your Docker account, save the + recovery code, move 2FA to a new device, or turn 2FA off. +keywords: enable 2FA, disable 2FA, turn on 2FA, turn off 2FA, two-factor + authentication, Docker account, TOTP, authenticator app, QR code, + recovery code, new device, personal access token, Docker Hub +weight: 10 +aliases: + - /security/2fa/disable-2fa/ + - /security/for-developers/2fa/disable-2fa/ +--- + +{{< summary-bar feature_name="2FA" >}} + +Turn on two-factor authentication (2FA) to require a code from your +authenticator app when you sign in with your password. Turn it off to +sign in with your password alone, or to move 2FA to a new device. For +how 2FA works and what the recovery code does, see +[Two-factor authentication][overview]. + +## Prerequisites + +Before you turn on 2FA, you need: + +- A time-based one-time password (TOTP) authenticator app on your phone or + another device +- Your Docker account password +- A verified email address on your account + +Docker opens the 2FA settings after your email address is verified. + +> [!NOTE] +> +> If your organization enforces single sign-on (SSO), the **2FA** page +> tells you to contact your administrator. Your identity provider manages +> sign-in for your account. + +## Enable two-factor authentication + +To turn on 2FA for your Docker account: + +1. Sign in to your [Docker account](https://app.docker.com/login). +1. Select your avatar in the top-right corner, then select **Account + settings**. +1. Select **2FA**. +1. Enter your account password, then select **Confirm**. +1. Save your recovery code. Select **Copy**, or open the menu next to + **Copy** and select **Download** or **Print**. +1. Open your authenticator app. Scan the code on the **QR Code** tab, or + enter the code from the **Text Code** tab. +1. Enter the six-digit code from your authenticator app in + **Authentication code**. +1. Select **Enable 2FA**. + +Two-factor authentication is on. When you sign in with your password, +Docker asks for a code from your authenticator app. Docker also emails +you a reminder to save your recovery code. + +> [!IMPORTANT] +> +> The recovery code works once. Using it signs you in and turns 2FA off. +> Keep it somewhere safe. If you lose both your authenticator app and your +> recovery code, contact Docker Support to recover your account. + +To sign in with `docker login -u`, or from scripts and CI, use a +[personal access token][pat] in place of your password. + +## Disable two-factor authentication + +> [!WARNING] +> +> Turning off 2FA leaves your account protected by your password alone. + +1. Sign in to your [Docker account](https://app.docker.com/login). +1. Select your avatar in the top-right corner, then select **Account + settings**. +1. Select **2FA**. +1. Enter your password, then select **Confirm**. +1. Select **Disable 2FA**. + +Two-factor authentication is off. Docker emails you to confirm the +change. + +## Move 2FA to a new device + +Docker keeps one authenticator per account. To move 2FA to a new phone or +device, [turn 2FA off](#disable-two-factor-authentication), then +[turn it on again](#enable-two-factor-authentication) from the new +device. Setup is not available while 2FA is on. + +## Next steps + +- [Recover your account][recover] if you lose your authenticator app or + recovery code. +- Create a [personal access token][pat] for the Docker CLI and automation. + +[overview]: /manuals/security/authentication/2fa/_index.md +[pat]: /manuals/security/access-tokens/personal-access-tokens.md +[recover]: /manuals/security/authentication/2fa/recover-hub-account.md diff --git a/content/manuals/security/authentication/2fa/recover-hub-account.md b/content/manuals/security/authentication/2fa/recover-hub-account.md index 0f31a5e60bc..34779041b00 100644 --- a/content/manuals/security/authentication/2fa/recover-hub-account.md +++ b/content/manuals/security/authentication/2fa/recover-hub-account.md @@ -79,5 +79,5 @@ Docker Support. - [Turn on 2FA][enable] again after you recover your account. - Create a [personal access token][pat] for the Docker CLI and automation. -[enable]: /manuals/security/authentication/2fa/_index.md +[enable]: /manuals/security/authentication/2fa/manage.md [pat]: /manuals/security/access-tokens/personal-access-tokens.md From d942859048b42efcd5d3233a7b38bfcebb1bc99d Mon Sep 17 00:00:00 2001 From: Alexa Date: Wed, 30 Sep 2026 14:53:30 -0500 Subject: [PATCH 4/5] security: trim repeated 2FA concepts from the task pages Keep how 2FA works, when Docker asks for the code, and recovery-code behavior on the overview so the manage and recover pages stay procedural. Co-authored-by: Cursor --- .../security/authentication/2fa/_index.md | 48 +++++-------------- .../security/authentication/2fa/manage.md | 36 ++++---------- .../authentication/2fa/recover-hub-account.md | 33 +++++-------- 3 files changed, 35 insertions(+), 82 deletions(-) diff --git a/content/manuals/security/authentication/2fa/_index.md b/content/manuals/security/authentication/2fa/_index.md index 4585fcd3c6e..94438ebf125 100644 --- a/content/manuals/security/authentication/2fa/_index.md +++ b/content/manuals/security/authentication/2fa/_index.md @@ -1,12 +1,12 @@ --- -title: Two-factor authentication for your Docker account +title: Two-factor authentication for your individual Docker account linkTitle: Two-factor authentication description: >- Learn how two-factor authentication protects a Docker account, when Docker asks for the code, and what the recovery code does. -keywords: two-factor authentication, 2FA, how 2FA works, Docker account, - TOTP, authenticator app, authentication code, recovery code, personal - access token, docker login, account security, Docker Hub +keywords: two-factor authentication, 2FA, individual Docker account, TOTP, + authenticator app, authentication code, recovery code, personal access + token, docker login, Account settings, Docker Hub, account security weight: 20 aliases: - /docker-hub/2fa/ @@ -31,30 +31,21 @@ Two-factor authentication (2FA) adds a code from an authenticator app to your password when you sign in to your Docker account. Someone who knows your password still needs the code from your device to sign in. -2FA is a setting on individual Docker accounts. You turn it on and off -yourself in **Account settings**. Organization and company settings do not -include 2FA. To control how members sign in across an organization, use -[single sign-on](/manuals/security/authentication/single-sign-on/_index.md). +> [!TIP] +> +> Organization and company settings do not include 2FA. To control how +> members sign in across an organization, use +> [single sign-on](/manuals/security/authentication/single-sign-on/_index.md). ## How two-factor authentication works When you turn on 2FA, you pair a time-based one-time password (TOTP) authenticator app with your account by scanning a QR code or entering a -text code. Any authenticator app that supports TOTP works. The app then -shows a six-digit code that changes every 30 seconds. - -After you enter your password, Docker shows the **Two-Factor -Authentication** page. Enter the code from your app in -**Authentication Code** and select **Verify**. If you no longer have the -device, select **I've lost my authentication device** to sign in with -your recovery code instead. - -A wrong code fails with `Invalid one-time password`. After repeated -failures, Docker returns `Too many failed login attempts` and blocks -further attempts for a short time. +text code. Any authenticator app that supports TOTP works. Docker keeps +one authenticator per account. -Docker keeps one authenticator per account. To move 2FA to a new device, -turn it off and turn it on again from the new device. +After repeated wrong codes, Docker returns `Too many failed login +attempts` and blocks further attempts for a short time. ## When Docker asks for the code @@ -71,19 +62,6 @@ Docker gives you one recovery code when you turn on 2FA. The code signs you in if you lose your authenticator app, so copy, download, or print it and store it somewhere safe. -> [!IMPORTANT] -> -> The recovery code works once. Using it on the **Lost Authentication -> Device** page signs you in, turns 2FA off, and deletes the code. Turn -> 2FA on again from your new device as soon as you are signed in. - -- **Generate new code** replaces the previous code. Only the latest code - works. -- Docker asks for your password before it shows the code or lets you - change 2FA settings. -- If you lose both the authenticator app and the recovery code, contact - Docker Support to recover your account. - Docker emails the verified address on your account when you turn 2FA on or off, when a recovery code is generated, and when a recovery code is used to sign in. The email does not contain the code. diff --git a/content/manuals/security/authentication/2fa/manage.md b/content/manuals/security/authentication/2fa/manage.md index c0c62c04f58..19468f28685 100644 --- a/content/manuals/security/authentication/2fa/manage.md +++ b/content/manuals/security/authentication/2fa/manage.md @@ -15,11 +15,11 @@ aliases: {{< summary-bar feature_name="2FA" >}} -Turn on two-factor authentication (2FA) to require a code from your -authenticator app when you sign in with your password. Turn it off to -sign in with your password alone, or to move 2FA to a new device. For -how 2FA works and what the recovery code does, see -[Two-factor authentication][overview]. +Turn two-factor authentication (2FA) on or off for your Docker account +in **Account settings**. Setup is not available while 2FA is on, so +moving 2FA to a new device means turning it off and on again. For how +2FA works, when Docker asks for the code, and what the recovery code +does, see [Two-factor authentication][overview]. ## Prerequisites @@ -30,14 +30,6 @@ Before you turn on 2FA, you need: - Your Docker account password - A verified email address on your account -Docker opens the 2FA settings after your email address is verified. - -> [!NOTE] -> -> If your organization enforces single sign-on (SSO), the **2FA** page -> tells you to contact your administrator. Your identity provider manages -> sign-in for your account. - ## Enable two-factor authentication To turn on 2FA for your Docker account: @@ -59,15 +51,6 @@ Two-factor authentication is on. When you sign in with your password, Docker asks for a code from your authenticator app. Docker also emails you a reminder to save your recovery code. -> [!IMPORTANT] -> -> The recovery code works once. Using it signs you in and turns 2FA off. -> Keep it somewhere safe. If you lose both your authenticator app and your -> recovery code, contact Docker Support to recover your account. - -To sign in with `docker login -u`, or from scripts and CI, use a -[personal access token][pat] in place of your password. - ## Disable two-factor authentication > [!WARNING] @@ -86,16 +69,17 @@ change. ## Move 2FA to a new device -Docker keeps one authenticator per account. To move 2FA to a new phone or -device, [turn 2FA off](#disable-two-factor-authentication), then +To move 2FA to a new phone or device, +[turn 2FA off](#disable-two-factor-authentication), then [turn it on again](#enable-two-factor-authentication) from the new -device. Setup is not available while 2FA is on. +device. ## Next steps - [Recover your account][recover] if you lose your authenticator app or recovery code. -- Create a [personal access token][pat] for the Docker CLI and automation. +- Create a [personal access token][pat] to sign in from the Docker CLI, + scripts, and CI. [overview]: /manuals/security/authentication/2fa/_index.md [pat]: /manuals/security/access-tokens/personal-access-tokens.md diff --git a/content/manuals/security/authentication/2fa/recover-hub-account.md b/content/manuals/security/authentication/2fa/recover-hub-account.md index 34779041b00..240cc910536 100644 --- a/content/manuals/security/authentication/2fa/recover-hub-account.md +++ b/content/manuals/security/authentication/2fa/recover-hub-account.md @@ -5,8 +5,8 @@ description: >- Sign in with a recovery code, generate a new recovery code, or contact Support when you lose your authenticator app. keywords: account recovery, two-factor authentication, 2FA, recovery code, - lost authenticator app, 2FA lockout, Docker account, generate recovery - code + Lost Authentication Device, lost authenticator app, 2FA lockout, Docker + account, Generate new code, Docker Support aliases: - /docker-hub/2fa/recover-hub-account/ - /security/for-developers/2fa/recover-hub-account/ @@ -17,16 +17,15 @@ weight: 20 {{< summary-bar feature_name="2FA" >}} -Get back into your Docker account when part of your two-factor -authentication (2FA) setup is missing. What you do depends on what you -still have: +Get back into your Docker account when you lose your authenticator app, +your recovery code, or both. Docker asks for your password before it +shows or replaces the recovery code. -- You lost your recovery code and can still sign in. - [Generate a new recovery code](#generate-a-new-recovery-code). -- You lost your authenticator app and still have your recovery code. - [Sign in with your recovery code](#sign-in-with-your-recovery-code). -- You lost both your authenticator app and your recovery code. - [Contact Docker Support](#contact-docker-support). +> [!IMPORTANT] +> +> The recovery code works once. Using it on the **Lost Authentication +> Device** page signs you in, turns 2FA off, and deletes the code. Turn +> 2FA on again from your new device as soon as you're signed in. ## Generate a new recovery code @@ -49,11 +48,6 @@ Select the visibility icon to view the new code. Then select **Copy**, If you lost your authenticator app and still have your recovery code, use the code to sign in. -> [!IMPORTANT] -> -> The recovery code works once. Using it signs you in and turns 2FA off. -> Turn 2FA on again from your new device as soon as you're signed in. - 1. Sign in to your [Docker account](https://app.docker.com/login) with your username and password. 1. On the **Two-Factor Authentication** page, select **I've lost my @@ -65,11 +59,8 @@ You're signed in and 2FA is off. To protect your account again, follow ## Contact Docker Support -If you lose both your authenticator app and your recovery code, contact -Docker Support to restore access. - -Open the -[Contact Support](https://hub.docker.com/support/contact/?category=2fa-lockout). +If you lost both your authenticator app and your recovery code, open the +[Contact Support form](https://hub.docker.com/support/contact/?category=2fa-lockout). The subject and description already describe a 2FA lockout. Enter the email address on your Docker account, then follow the instructions from Docker Support. From 690bc6e236be6181db9eb41dc1b46d4c85c60e68 Mon Sep 17 00:00:00 2001 From: Alexa Date: Thu, 1 Oct 2026 07:44:56 -0500 Subject: [PATCH 5/5] security: drop the SSO row and setup sentence from the 2FA pages The sign-in table on the 2FA overview had a row for enforced SSO, which does not apply to the individual accounts this page covers. The manage page opened with a sentence about setup being unavailable while 2FA is on, which repeated the Move 2FA to a new device section. Co-authored-by: Cursor --- content/manuals/security/authentication/2fa/_index.md | 1 - content/manuals/security/authentication/2fa/manage.md | 7 +++---- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/content/manuals/security/authentication/2fa/_index.md b/content/manuals/security/authentication/2fa/_index.md index 94438ebf125..4f107547d2e 100644 --- a/content/manuals/security/authentication/2fa/_index.md +++ b/content/manuals/security/authentication/2fa/_index.md @@ -54,7 +54,6 @@ attempts` and blocks further attempts for a short time. | Browser sign-in to Docker Home or Docker Hub | Your password, then the code from your authenticator app | | `docker login` with no username | The same browser sign-in, if the browser is not already signed in | | `docker login -u`, scripts, and CI | A [personal access token](/manuals/security/access-tokens/personal-access-tokens.md) in the password prompt. Password sign-in from the CLI is not supported when 2FA is on | -| Enforced single sign-on | No code. Your identity provider handles sign-in, and the **2FA** page tells you to contact your administrator | ## Recovery code diff --git a/content/manuals/security/authentication/2fa/manage.md b/content/manuals/security/authentication/2fa/manage.md index 19468f28685..3284b09900c 100644 --- a/content/manuals/security/authentication/2fa/manage.md +++ b/content/manuals/security/authentication/2fa/manage.md @@ -16,10 +16,9 @@ aliases: {{< summary-bar feature_name="2FA" >}} Turn two-factor authentication (2FA) on or off for your Docker account -in **Account settings**. Setup is not available while 2FA is on, so -moving 2FA to a new device means turning it off and on again. For how -2FA works, when Docker asks for the code, and what the recovery code -does, see [Two-factor authentication][overview]. +in **Account settings**. For how 2FA works, when Docker asks for the +code, and what the recovery code does, see +[Two-factor authentication][overview]. ## Prerequisites