Revise MFA documentation for clarity and completeness

docs/guides/modules/permissions-authentication/pages/mfa.adoc

@@ -1,19 +1,16 @@
 = Multi-factor authentication (MFA)
 :page-platform: Cloud
-:page-description: MFA Overview
+:page-description: MFA overview, setup, recovery, and reset process for CircleCI accounts.
 :experimental:
 
-NOTE:  MFA is currently optional. Starting December 1, 2025 MFA will be required if you log in to CircleCI with email and password.
+NOTE: MFA is currently optional. Starting December 1, 2025, MFA will be required if you log in to CircleCI with your email and password.
 
-Multi-factor authentication (MFA) for CircleCI is available if you sign in to your CircleCI account using email and password. If you use a social login method to access your CircleCI account (such as GitHub or Bitbucket), you can use your login provider's MFA offering.
+Multi-factor authentication (MFA) for CircleCI is available if you sign in to your CircleCI account using email and password. If you use a social login method (such as GitHub or Bitbucket), you must use your provider's MFA.
 
 [#introduction]
 == Introduction
 
-MFA is an additional layer of security for your CircleCI account. We strongly recommend that you set up and enable it.
-With MFA enabled, an additional verification step is required to access your account and make changes to account authentication settings, such as email or password.
-This means that even if your account password is compromised, only someone with access to the additional verification factor can
-access the account. The additional verification step takes the form of providing a one-time password (OTP).
+MFA is an additional layer of security for your CircleCI account. With MFA enabled, an additional verification step is required to access your account and make changes to authentication settings, such as email or password. This means that even if your account password is compromised, only someone with access to the additional verification factor can access the account. The additional verification step involves providing a one-time password (OTP).
 
 [#setup-mfa]
 == Set up MFA
@@ -22,65 +19,105 @@ To configure MFA on your account, follow these steps:
 
 . In the link:https://app.circleci.com/home/[CircleCI web app], select your profile from the upper right corner, then select **User Settings**.
 . Select **Password & authentication** from the sidebar.
-. On the Password & authentication page, in the **Multi-factor authentication** section, select **Add authenticator app**. MFA is marked as **Not enabled** until a factor is added.
-. Input your password at the password prompt.
-. At the **Add authenticator app** prompt, scan the provided QR code using an authenticator app or browser extension. Then verify the code generated by the app, by inputting it into the provided text box.
-. At the next screen, you are provided with the MFA recovery code. You must copy this code and save it somewhere safe. This code will only be displayed once and is the last resort for accessing your account in the event that you lose access to your MFA factor. Without this code, you would lose access to your account.
-. You may close the window to complete the setup. When MFA is successfully configured, it is marked as **Enabled** on the Password & authentication page.
++
+TIP: If you do not see this option you have signed in to CircleCI with a social login method (such as GitHub or Bitbucket). You must use your provider's MFA to enable MFA on your CircleCI account.
+. In the "Multi-factor authentication" section, select btn:[Add authenticator app]. MFA is marked as "Not enabled" until a factor is added.
+. Input your password at the password prompt. This is the password you use to sign in to CircleCI.
+. At the **Add authenticator app** prompt, scan the provided QR code using an authenticator app or browser extension. Then, verify the code generated by the app by inputting it into the provided text box.
+. At the next screen, you are provided with the MFA recovery code. **Copy this code and save it somewhere safe.** This code will only be displayed once and is the last resort for accessing your account if you lose access to your MFA factor.
+. Close the window to complete the setup. When MFA is successfully configured, it is marked as **Enabled** on the Password & authentication page.
 
 image::guides:ROOT:authentication/mfa-enabled.png[Password and authentication page with MFA enabled]
 
 [#using-mfa]
 == Using MFA on your account
 
-Once you have MFA enabled, then you must provide a second verification factor whenever you log into your account.
+Once you have MFA enabled, you must provide a second verification factor each time you log in to your account.
 
 image::guides:ROOT:authentication/mfa-otp-login.png[Login page with request for OTP]
 
-You will also be asked to provide a second factor whenever you attempt to change the authentication settings of your account (for example updating your email or password).
+You will also be asked to provide a second factor whenever you attempt to change your account's authentication settings (for example, updating your email or password).
 
-Currently CircleCI supports MFA using authenticator applications only. Once you have configured MFA, as per the previous section, then you must use the OTP generated by
-the application whenever this is requested in the CircleCI web app. The OTP will be displayed in the authenticator app, and you must input this code when prompted in the CircleCI web app.
+Currently, CircleCI supports MFA only via authenticator applications. The OTP will be displayed in the authenticator app, and you must enter it when prompted in the CircleCI web app.
 
 [#mfa-recovery-codes]
 == MFA recovery codes
 
-WARNING: If you have MFA enabled, and lose access to your MFA factor and recovery code, then you will lose access to your account. You must ensure that you do not lose the recovery code.
+WARNING: If you have MFA enabled and lose access to both your MFA factor and recovery code, you will lose access to your account. You must ensure that you do not lose the recovery code.
 
-If you lose access to your MFA factor (for example, by losing access to the authenticator application), you may use the recovery code as a second factor instead. A recovery code may only be used once, after which a new recovery code is generated and shared with you in the CircleCI web app. Whenever a new recovery code is generated, it is important to always save it somewhere safe.
+If you lose access to your MFA factor (for example, by losing the authenticator app), you can use the recovery code as a second factor. A recovery code may only be used once, after which a new recovery code is generated and shared with you in the CircleCI web app. You can always save the latest code in a safe place.
 
-It is also possible to intentionally regenerate your MFA recovery code. To do this, follow these steps:
+To intentionally regenerate your MFA recovery code:
 
 . In the link:https://app.circleci.com/home/[CircleCI web app], select your profile from the upper right corner, then select **User Settings**.
 . Select **Password & authentication** from the sidebar.
-. On the Password & authentication page, in the **Multi-factor authentication**section, select **Add/edit authenticator app**.
-. Input your password at the password prompt.
+. In the "Multi-factor authentication" section, select btn:[Add/edit authenticator app].
+. Input your password at the password prompt. This is the password you use to sign in to CircleCI.
 . Input your OTP at the OTP prompt. Once these have been successfully submitted, your OTP ID and recovery code ID will be displayed.
 . Select the button to **Regenerate recovery code** on the recovery code row.
-. At the prompt to regenerate the recovery code, select `Yes, regenerate code`. This will generate a new code and invalidate the previous recovery code. Store the new code somewhere safe. It will not be displayed again.
+. At the prompt to regenerate the recovery code, select btn:[Yes, regenerate code]. This will generate a new recovery code and invalidate the previous one. Store the new code in a safe place. It will not be displayed again.
 
 image::guides:ROOT:authentication/mfa-regenerate-recovery-code.png[Password and authentication page with regenerate recovery code button]
 
 image::guides:ROOT:authentication/mfa-display-recovery-code.png[Password and authentication page displaying new recovery code]
 
+[#mfa-reset-process]
+== MFA Reset Process
+
+The MFA reset process depends on your situation and whether you retain access to your account.
+
+=== Scenario 1: You still have account access
+
+If you can log in and want to reconfigure your authenticator app or regenerate your recovery code:
+
+. Go to **User Settings** in the CircleCI web app.
+. Select **Password & authentication**.
+. In the **Multi-factor authentication** section, select **Add/edit authenticator app**.
+. Enter your password and OTP when prompted.
+. Follow the setup steps to scan the new QR code with your authenticator app.
+. Click **Regenerate recovery code** to generate a new code.
+. **Store the new recovery code securely** – it will only be displayed once, and the previous code becomes invalid.
+
+=== Scenario 2: You are locked out (no authenticator app or recovery code)
+
+If you have lost access to both your authenticator app and recovery code, you are locked out of your CircleCI account. CircleCI cannot bypass MFA for security reasons. The only way to regain access is through your recovery code. Support cannot reset MFA if you have no recovery code and cannot verify your identity.
+
+=== Scenario 3: Support-initiated MFA reset
+
+In some cases, if you are locked out but can verify your identity (such as by providing your login email address, account name, geographic location, IP address, or other account-specific information), CircleCI support may reset MFA on a case-by-case basis.
+
 [#faqs]
 == FAQs
 
-=== I have lost access to the device which has my authenticator app. What should I do now?
+=== I have lost access to the device that has my authenticator app. What should I do now?
 
-We strongly recommend that you save your recovery code somewhere secure, for this reason. If you have lost access to your second authentication factor,
-you can use the recovery code to authenticate. Then you can add a new MFA factor and delete the one which you can no longer access.
+You can use your recovery code to authenticate. Then you can add a new MFA factor and delete the one you can no longer access.
 
 === I have a new phone and don't want to lose my MFA factor. What should I do?
 
-If you have a new phone or MFA device, check the documentation of the authenticator app you are using for advice on how to transfer codes. Many
-authenticator apps support transferring codes to a new device.
+Check the documentation of your authenticator app for advice on how to transfer codes. Many authenticator apps support transferring codes to a new device.
 
 === Can I use the same authenticator app for multiple accounts?
 
-Yes, most authenticator apps support multiple accounts. You should check the documentation of your authenticator application to confirm.
+Yes, most authenticator apps support multiple accounts. Check your authenticator application's documentation to confirm.
 
 === My authenticator codes have stopped working when I try to use them. What should I do?
 
-If your authenticator codes are not working, this can be an indicator that your authenticator app is out of sync. First check that the time on your device is up-to-date.
-If the authenticator app you are using does not automatically sync time, check whether there is a setting to re-sync it. If you continue to have issues and are unable to use the OTP to authenticate, you may use your recovery code to authenticate instead. You can then remove and re-add the MFA factor.
+Check that the time on your device is up to date. If your authenticator app does not automatically sync time, check for a setting to re-sync it. If you continue to have issues and can't use the OTP, you can use your recovery code to authenticate instead. You can then remove and re-add the MFA factor.
+
+[#vcs-mfa]
+== Enabling MFA for VCS Logins
+
+- **GitHub:** Enable 2FA via GitHub's security settings.
+- **Bitbucket:** Enable 2FA via Bitbucket's security settings.
+
+CircleCI does not manage or enforce MFA for VCS logins – it relies entirely on the provider's authentication system.
+
+[#support-escalation]
+== Support Escalation Summary
+
+- **User has recovery code:** Guide them through self-service reset via User Settings.
+- **User locked out, no recovery code:** Escalate to support for identity verification and case-by-case assessment.
+- **VCS login issues:** Direct to VCS provider support.
+
+---