From 32eaeee6660270b3778b24ea13250ccd3c7df222 Mon Sep 17 00:00:00 2001 From: Isaac Durham Date: Wed, 10 Dec 2025 14:51:28 -0500 Subject: [PATCH 1/3] Reorganize Email OTP content --- .../account/two_factor_authentication.md | 54 ++++++++++++++++++- ...o_factor_authentication_troubleshooting.md | 18 +++++++ 2 files changed, 70 insertions(+), 2 deletions(-) diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index edbff2aadb544d..ea1d18b2c90f44 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -22,12 +22,14 @@ GitLab supports the following 2FA methods: - One-time password ([OTP](https://datatracker.ietf.org/doc/html/rfc6238)) authenticators. During sign in, GitLab prompts you for a code generated by your OTP authenticator. - WebAuthn devices. During sign in, GitLab prompts you to prove ownership of your WebAuthn device. This is generally a physical device like a YubiKey, your phone, or your laptop. +- Email OTP. During sign in, GitLab prompts you for a code sent to your email address. If you set up a device, also set up an OTP so you can still access your account if you lose the device. ## Enable two-factor authentication -To enable 2FA, verify your email address and register an OTP authenticator or WebAuthn device. +To enable 2FA, verify your email address and register an OTP authenticator, a WebAuthn device, +or email OTP. ### Register an OTP authenticator @@ -132,6 +134,42 @@ You can lose access to your account if you clear your browser data. {{< /alert >}} +### Enable email OTP + +{{< history >}} + +- [Introduced](https://issue-link) in GitLab 18.7 [with a feature flag](../../../administration/feature_flags/_index.md) named `email_based_mfa`. Disabled by default. +- [Enabled on GitLab.com](https://issue-link) in GitLab 18.7. This feature is being progressively enabled for all users throughout 2026. + +{{< /history >}} + +{{< alert type="flag" >}} + +The availability of this feature is controlled by a feature flag. For more information, see the history. + +{{< /alert >}} + +Email OTP allows you to verify your identity by sending a six-digit verification code to your email address. + +{{< alert type="note" >}} + +You might be unable to use email OTP if: + +- Your group policy requires the use of other two-factor authentication methods. +- Your account uses an external identity provider. +- Your account has been scheduled for automatic enablement at a future date. + +{{< /alert >}} + +To enable email OTP for your account: + +1. In the upper-right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select **Account**. +1. Select **Manage two-factor authentication**. +1. Select **Enable email OTP**. +1. Enter your current password and select **Update email OTP settings**. + ### Add a Cisco Duo authenticator {{< details >}} @@ -360,7 +398,7 @@ method you registered. ### Sign in with an OTP authenticator -When asked, enter the pin from your OTP authenticator or a recovery code to sign in. +When prompted, enter the pin from your OTP authenticator or a recovery code to sign in. ### Sign in with a WebAuthn device @@ -370,6 +408,18 @@ or pressing its button) after entering your credentials. A message displays indicating that your device responded to the authentication request and you're automatically signed in. +### Sign in with email OTP + +When prompted, enter the six-digit verification code that is sent to your email. +The code remains valid for 60 minutes. + +If you are unable to use the access code, you can: + +- Request a new code, select **Resend code** from the sign in page. +- Send a code to another verified email address, select **Send a code to + another address associated with this account** from the sign in page. +- See [Email OTP troubleshooting](two_factor_authentication_troubleshooting.md#email-otp-troubleshooting). + ### Sign in with a personal access token When 2FA is enabled, you cannot use your password to authenticate with Git over HTTPS or the diff --git a/doc/user/profile/account/two_factor_authentication_troubleshooting.md b/doc/user/profile/account/two_factor_authentication_troubleshooting.md index 902e4a28120a4e..d0e56f7980f883 100644 --- a/doc/user/profile/account/two_factor_authentication_troubleshooting.md +++ b/doc/user/profile/account/two_factor_authentication_troubleshooting.md @@ -76,6 +76,24 @@ This issue occurs if you are using a non-default SSH key pair file path and atte To resolve this, [configure SSH to point to a different directory](../../ssh.md#configure-ssh-to-point-to-a-different-directory) using `ssh-agent`. +## Email OTP troubleshooting + +### Didn't receive email verification code or code has expired + +Check your spam folder. On GitLab.com, emails are sent from `gitlab@mg.gitlab.com` +and can be [verified as genuine](https://handbook.gitlab.com/handbook/security/corporate/systems/google/mail/verification/#verify-an-email-from-gitlabcom-is-genuine). + +If your code expires, you can request a new code. From the sign-in page, select **Resend code**. + +### Unable to access your email address + +If you cannot access your primary email address, try a verified secondary email address associated +to your account. From the sign-in page, select **Send a code to another address associated with +this account**. + +On GitLab Self-Managed, if you are unable to access your primary or secondary email addresses, +contact your GitLab administrator. + ## Recovery options and 2FA reset ### Use a recovery code -- GitLab From 1a151f531ee7ed263184cd12761fa531b3191402 Mon Sep 17 00:00:00 2001 From: Isaac Durham Date: Thu, 11 Dec 2025 11:03:58 -0500 Subject: [PATCH 2/3] Remove missing issue links --- doc/user/profile/account/two_factor_authentication.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index ea1d18b2c90f44..42878c212737b2 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -138,8 +138,8 @@ You can lose access to your account if you clear your browser data. {{< history >}} -- [Introduced](https://issue-link) in GitLab 18.7 [with a feature flag](../../../administration/feature_flags/_index.md) named `email_based_mfa`. Disabled by default. -- [Enabled on GitLab.com](https://issue-link) in GitLab 18.7. This feature is being progressively enabled for all users throughout 2026. +- Introduced in GitLab 18.7 [with a feature flag](../../../administration/feature_flags/_index.md) named `email_based_mfa`. Disabled by default. +- Enabled on GitLab.com in GitLab 18.7. This feature is being progressively enabled for all users throughout 2026. {{< /history >}} -- GitLab From f63fc2ab1b81d4749e5469adf709d1691b8c5a76 Mon Sep 17 00:00:00 2001 From: Isaac Durham Date: Thu, 11 Dec 2025 12:19:45 -0500 Subject: [PATCH 3/3] Apply suggestions from feedback --- doc/user/profile/account/two_factor_authentication.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 42878c212737b2..263040fd608497 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -139,7 +139,7 @@ You can lose access to your account if you clear your browser data. {{< history >}} - Introduced in GitLab 18.7 [with a feature flag](../../../administration/feature_flags/_index.md) named `email_based_mfa`. Disabled by default. -- Enabled on GitLab.com in GitLab 18.7. This feature is being progressively enabled for all users throughout 2026. +- Enabled on GitLab.com in GitLab 18.7, with progressive rollout to all users throughout 2026. {{< /history >}} @@ -157,7 +157,7 @@ You might be unable to use email OTP if: - Your group policy requires the use of other two-factor authentication methods. - Your account uses an external identity provider. -- Your account has been scheduled for automatic enablement at a future date. +- Your account is scheduled for automatic enablement at a future date. {{< /alert >}} @@ -415,9 +415,9 @@ The code remains valid for 60 minutes. If you are unable to use the access code, you can: -- Request a new code, select **Resend code** from the sign in page. -- Send a code to another verified email address, select **Send a code to - another address associated with this account** from the sign in page. +- Request a new code. On the sign in page, select **Resend code**. +- Send a code to another verified email address. On the sign in page, select **Send a code to + another address associated with this account**. - See [Email OTP troubleshooting](two_factor_authentication_troubleshooting.md#email-otp-troubleshooting). ### Sign in with a personal access token -- GitLab