diff --git a/content/manuals/accounts/individual/_index.md b/content/manuals/accounts/individual/_index.md index ad0cf10392c1..2bc9ddc59a20 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 3db92002274e..766a75f8912b 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 616abe7bfac1..a841bdbb1f48 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 d438674ad0c8..4f107547d2ec 100644 --- a/content/manuals/security/authentication/2fa/_index.md +++ b/content/manuals/security/authentication/2fa/_index.md @@ -1,81 +1,70 @@ --- -title: Enable two-factor authentication for your Docker account +title: Two-factor authentication for your individual 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 + 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, 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/ - - /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 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 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 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. - -## Key benefits - -Two-factor authentication improves your account security: - -- 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. +> [!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). -## Prerequisites +## How two-factor authentication works -Before turning on two-factor authentication, you need: +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. Docker keeps +one authenticator per account. -- A smartphone or device with a time-based one-time password (TOTP) - authenticator app installed -- Access to your Docker account password +After repeated wrong codes, Docker returns `Too many failed login +attempts` and blocks further attempts for a short time. -## Enable two-factor authentication +## When Docker asks for the code -To turn on 2FA for your Docker account: +| 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 | -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 - 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. Select **Enable 2FA**. +## Recovery code -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. +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. -## Disable two-factor authentication +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. -> [!WARNING] -> -> Disabling two-factor authentication results in decreased security for your -> Docker account. +## Next steps -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 - settings**. -1. Select **2FA**. -1. Enter your password, then select **Confirm**. -1. Select **Disable 2FA**. +{{< grid >}} diff --git a/content/manuals/security/authentication/2fa/manage.md b/content/manuals/security/authentication/2fa/manage.md new file mode 100644 index 000000000000..3284b09900cc --- /dev/null +++ b/content/manuals/security/authentication/2fa/manage.md @@ -0,0 +1,85 @@ +--- +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 two-factor authentication (2FA) on or off for your Docker account +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 + +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 + +## 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. + +## 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 + +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. + +## Next steps + +- [Recover your account][recover] if you lose your authenticator app or + recovery code. +- 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 +[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 dcf6cd19c815..240cc9105364 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 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/ @@ -16,32 +17,58 @@ 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. +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. + +> [!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 -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 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) 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 in the top-right corner, then 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 select **Copy**, +**Download**, or **Print**, and store the code somewhere safe. + +## Sign in with your recovery code + +If you lost your authenticator app and still have your recovery code, use +the code to sign 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 +[Turn on 2FA][enable]. + +## Contact Docker Support + +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. -## Recover your account without access +## Next steps -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. +- [Turn on 2FA][enable] again after you recover your account. +- Create a [personal access token][pat] for the Docker CLI and automation. -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]: /manuals/security/authentication/2fa/manage.md +[pat]: /manuals/security/access-tokens/personal-access-tokens.md