diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index edbff2aadb544d49648919b9ad4840af33a91425..263040fd6084975b4705f899879f5e0950368ed2 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 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, with progressive rollout to 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 is 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. 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 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 902e4a28120a4ea09bf3b8ed10f50de07b91b1f4..d0e56f7980f883146ccfff3dbf019415a41d18fa 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