From d298c1e1665f8a3267f58cc94293c90e4117971b Mon Sep 17 00:00:00 2001
From: Brendan Lynch <blynch@gitlab.com>
Date: Fri, 26 Jul 2024 15:05:47 +0000
Subject: [PATCH] Apply 1 suggestion(s) to 1 file(s)
Co-authored-by: Marcel Amirault <mamirault@gitlab.com>
---
app/views/profiles/accounts/show.html.haml | 2 +-
.../profiles/two_factor_auths/show.html.haml | 4 +-
doc/development/gitlab_shell/features.md | 2 +-
doc/topics/git/troubleshooting_git.md | 2 +-
doc/user/enterprise_user/index.md | 2 +-
doc/user/packages/dependency_proxy/index.md | 2 +-
.../account/two_factor_authentication.md | 139 +---------------
...o_factor_authentication_troubleshooting.md | 155 ++++++++++++++++++
.../profiles/two_factor_auths_spec.rb | 2 +-
9 files changed, 165 insertions(+), 145 deletions(-)
create mode 100644 doc/user/profile/account/two_factor_authentication_troubleshooting.md
diff --git a/app/views/profiles/accounts/show.html.haml b/app/views/profiles/accounts/show.html.haml
index 4bb0f18b99fd4..b04781ecad6df 100644
--- a/app/views/profiles/accounts/show.html.haml
+++ b/app/views/profiles/accounts/show.html.haml
@@ -13,7 +13,7 @@
alert_options: { class: 'gl-my-5' },
close_button_options: { class: 'js-close-2fa-enabled-success-alert' }) do |c|
- c.with_body do
- = html_escape(_('You have set up 2FA for your account! If you lose access to your 2FA device, you can use your recovery codes to access your account. Alternatively, if you upload an SSH key, you can %{anchorOpen}use that key to generate additional recovery codes%{anchorClose}.')) % { anchorOpen: '<a href="%{href}">'.html_safe % { href: help_page_path('user/profile/account/two_factor_authentication', anchor: 'generate-new-recovery-codes-using-ssh') }, anchorClose: '</a>'.html_safe }
+ = html_escape(_('You have set up 2FA for your account! If you lose access to your 2FA device, you can use your recovery codes to access your account. Alternatively, if you upload an SSH key, you can %{anchorOpen}use that key to generate additional recovery codes%{anchorClose}.')) % { anchorOpen: '<a href="%{href}">'.html_safe % { href: help_page_path('user/profile/account/two_factor_authentication_troubleshooting', anchor: 'generate-new-recovery-codes-using-ssh') }, anchorClose: '</a>'.html_safe }
.settings-section.js-search-settings-section
.settings-sticky-header
diff --git a/app/views/profiles/two_factor_auths/show.html.haml b/app/views/profiles/two_factor_auths/show.html.haml
index 045d6820e5f20..89b35c847e483 100644
--- a/app/views/profiles/two_factor_auths/show.html.haml
+++ b/app/views/profiles/two_factor_auths/show.html.haml
@@ -41,7 +41,7 @@
alert_options: { class: 'gl-mb-3' },
dismissible: false) do |c|
- c.with_body do
- = link_to _('Try the troubleshooting steps here.'), help_page_path('user/profile/account/two_factor_authentication', anchor: 'troubleshooting'), target: '_blank', rel: 'noopener noreferrer'
+ = link_to _('Try the troubleshooting steps here.'), help_page_path('user/profile/account/two_factor_authentication_troubleshooting'), target: '_blank', rel: 'noopener noreferrer'
- if current_password_required?
.form-group
@@ -130,7 +130,7 @@
alert_options: { class: 'gl-mb-3' },
dismissible: false) do |c|
- c.with_body do
- = link_to _('Try the troubleshooting steps here.'), help_page_path('user/profile/account/two_factor_authentication', anchor: 'troubleshooting'), target: '_blank', rel: 'noopener noreferrer'
+ = link_to _('Try the troubleshooting steps here.'), help_page_path('user/profile/account/two_factor_authentication_troubleshooting'), target: '_blank', rel: 'noopener noreferrer'
.js-manage-two-factor-form{ data: { current_password_required: current_password_required?.to_s, profile_two_factor_auth_path: profile_two_factor_auth_path, profile_two_factor_auth_method: 'delete', codes_profile_two_factor_auth_path: codes_profile_two_factor_auth_path, codes_profile_two_factor_auth_method: 'post' } }
- else
%p
diff --git a/doc/development/gitlab_shell/features.md b/doc/development/gitlab_shell/features.md
index c34e430e520c2..ef8db35491cea 100644
--- a/doc/development/gitlab_shell/features.md
+++ b/doc/development/gitlab_shell/features.md
@@ -40,7 +40,7 @@ It limits the set of commands to predefined Git commands:
## Generate new 2FA recovery codes
Enables users to
-[generate new 2FA recovery codes](../../user/profile/account/two_factor_authentication.md#generate-new-recovery-codes-using-ssh):
+[generate new 2FA recovery codes](../../user/profile/account/two_factor_authentication_troubleshooting.md#generate-new-recovery-codes-using-ssh):
```shell
$ ssh git@<hostname> 2fa_recovery_codes
diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md
index 68067aae2e58a..2cc78a4d2881f 100644
--- a/doc/topics/git/troubleshooting_git.md
+++ b/doc/topics/git/troubleshooting_git.md
@@ -355,7 +355,7 @@ The bug was reported [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issu
## Error on Git fetch: "HTTP Basic: Access Denied"
If you receive an `HTTP Basic: Access denied` error when using Git over HTTP(S),
-refer to the [two-factor authentication troubleshooting guide](../../user/profile/account/two_factor_authentication.md#troubleshooting).
+refer to the [two-factor authentication troubleshooting guide](../../user/profile/account/two_factor_authentication_troubleshooting.md).
## `401` errors logged during successful `git clone`
diff --git a/doc/user/enterprise_user/index.md b/doc/user/enterprise_user/index.md
index 8da8f96847596..d19de17b3b56b 100644
--- a/doc/user/enterprise_user/index.md
+++ b/doc/user/enterprise_user/index.md
@@ -225,4 +225,4 @@ Changing an enterprise user's primary email to an email from a non-verified doma
### Cannot disable two-factor authentication for an enterprise user
-If an enterprise user does not have an **Enterprise** badge, a top-level group Owner cannot [disable or reset 2FA](#disable-two-factor-authentication) for that user. Instead, the Owner should tell the enterprise user to consider available [recovery options](../profile/account/two_factor_authentication.md#recovery-options).
+If an enterprise user does not have an **Enterprise** badge, a top-level group Owner cannot [disable or reset 2FA](#disable-two-factor-authentication) for that user. Instead, the Owner should tell the enterprise user to consider available [recovery options](../profile/account/two_factor_authentication_troubleshooting.md#recovery-options-and-2fa-reset).
diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md
index 91d9431d2a864..f16ac0274ca93 100644
--- a/doc/user/packages/dependency_proxy/index.md
+++ b/doc/user/packages/dependency_proxy/index.md
@@ -298,7 +298,7 @@ hub_docker_quota_check:
### Authentication error: "HTTP Basic: Access Denied"
-If you receive an `HTTP Basic: Access denied` error when authenticating against the Dependency Proxy, refer to the [two-factor authentication troubleshooting guide](../../profile/account/two_factor_authentication.md#troubleshooting).
+If you receive an `HTTP Basic: Access denied` error when authenticating against the Dependency Proxy, refer to the [two-factor authentication troubleshooting guide](../../profile/account/two_factor_authentication_troubleshooting.md).
### Dependency Proxy Connection Failure
diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md
index 3a3eb116e58c9..3d6d46a1dea9d 100644
--- a/doc/user/profile/account/two_factor_authentication.md
+++ b/doc/user/profile/account/two_factor_authentication.md
@@ -349,7 +349,7 @@ Recovery codes are not generated for WebAuthn devices.
If you lose the recovery codes, or want to generate new ones, you can use either:
- The [2FA account settings](#regenerate-two-factor-authentication-recovery-codes) page.
-- [SSH](#generate-new-recovery-codes-using-ssh).
+- [SSH](two_factor_authentication_troubleshooting.md#generate-new-recovery-codes-using-ssh).
### Regenerate two-factor authentication recovery codes
@@ -371,7 +371,7 @@ and you're presented with a second prompt, depending on which type of 2FA you've
### Sign in using a one-time password
-When asked, enter the pin from your one-time password authenticator's application or a recovery code to sign in.
+When asked, enter the pin from your one-time password authenticator application or a recovery code to sign in.
### Sign in using a WebAuthn device
@@ -393,84 +393,6 @@ To disable 2FA:
This clears all your 2FA registrations, including mobile applications and WebAuthn devices.
-## Recovery options
-
-If you don't have access to your code generation device, you can recover access to your account:
-
-- [Use a saved recovery code](#use-a-saved-recovery-code), if you saved them when you enabled two-factor
- authentication.
-- [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh), if you didn't save your original
- recovery codes but have an SSH key.
-- [Have 2FA disabled on your account](#have-two-factor-authentication-disabled-on-your-account), if you don't have your
- recovery codes or an SSH key.
-
-### Use a saved recovery code
-
-To use a recovery code:
-
-1. Enter your username or email, and password, on the GitLab sign-in page.
-1. When prompted for a two-factor code, enter the recovery code.
-
-After you use a recovery code, you cannot re-use it. You can still use the other recovery codes you saved.
-
-### Generate new recovery codes using SSH
-
-If you forget to save your recovery codes when enabling 2FA, and you added an SSH key to your GitLab account, you can generate a new set of recovery codes with SSH:
-
-1. In a terminal, run:
-
- ```shell
- ssh git@gitlab.com 2fa_recovery_codes
- ```
-
- On self-managed instances, replace **`gitlab.com`** in the command above with the GitLab server hostname (`gitlab.example.com`).
-
-1. You are prompted to confirm that you want to generate new codes. This process invalidates previously-saved codes. For
- example:
-
- ```shell
- Are you sure you want to generate new two-factor recovery codes?
- Any existing recovery codes you saved will be invalidated. (yes/no)
-
- yes
-
- Your two-factor authentication recovery codes are:
-
- 119135e5a3ebce8e
- 11f6v2a498810dcd
- 3924c7ab2089c902
- e79a3398bfe4f224
- 34bd7b74adbc8861
- f061691d5107df1a
- 169bf32a18e63e7f
- b510e7422e81c947
- 20dbed24c5e74663
- df9d3b9403b9c9f0
-
- During sign in, use one of the codes above when prompted for your
- two-factor code. Then, visit your Profile Settings and add a new device
- so you do not lose access to your account again.
- ```
-
-1. Go to the GitLab sign-in page and enter your username or email, and password. When prompted for a two-factor code,
- enter one of the recovery codes obtained from the command-line output.
-
-After signing in, immediately set up 2FA with a new device.
-
-### Have two-factor authentication disabled on your account
-
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
-
-If other methods are unavailable, have a GitLab support contact submit a [support ticket](https://support.gitlab.com) to request
-a GitLab global administrator disable 2FA for your account:
-
-- This service is only available for accounts that have a GitLab.com subscription. For more information, see our
- [blog post](https://about.gitlab.com/blog/2020/08/04/gitlab-support-no-longer-processing-mfa-resets-for-free-users/).
-- Disabling this setting temporarily leaves your account in a less secure state. You should sign in and re-enable two-factor
- authentication as soon as possible.
-
## Information for GitLab administrators
DETAILS:
@@ -492,60 +414,3 @@ DETAILS:
the WebAuthn key has only been registered on `first.host.xyz`.
- To enforce 2FA at the system or group levels see, [Enforce two-factor authentication](../../../security/two_factor_authentication.md).
-
-## Troubleshooting
-
-### Error: "HTTP Basic: Access denied. The provided password or token ..."
-
-When making a request, you can receive the following error:
-
-```plaintext
-HTTP Basic: Access denied. The provided password or token is incorrect or your account has 2FA enabled and you must use a personal
-access token instead of a password.
-```
-
-This error occurs in the following scenarios:
-
-- You have 2FA enabled and have attempted to authenticate with a username and
- password.
-- You do not have 2FA enabled and have sent an incorrect username or password
- with your request.
-- You do not have 2FA enabled but an administrator has enabled the
- [enforce 2FA for all users](../../../security/two_factor_authentication.md#enforce-2fa-for-all-users) setting.
-- You do not have 2FA enabled, but an administrator has disabled the
- [password authentication enabled for Git over HTTP(S)](../../../administration/settings/sign_in_restrictions.md#password-authentication-enabled)
- setting.
-
-Instead you can authenticate:
-
-- Using a [personal access token](../personal_access_tokens.md) (PAT):
- - For Git requests over HTTP(S), a PAT with `read_repository` or `write_repository` scope is required.
- - For [GitLab container registry](../../packages/container_registry/authenticate_with_container_registry.md) requests, a PAT
- with `read_registry` or `write_registry` scope is required.
- - For [Dependency Proxy](../../packages/dependency_proxy/index.md#authenticate-with-the-dependency-proxy) requests, a PAT with
- `read_registry` and `write_registry` scopes is required.
-- If you have configured LDAP, using an [LDAP password](../../../administration/auth/ldap/index.md)
-- Using an [OAuth credential helper](#oauth-credential-helpers).
-
-### Error: "invalid pin code"
-
-If you receive an `invalid pin code` error, this can indicate that there is a time sync issue between the authentication
-application and the GitLab instance itself. To avoid the time sync issue, enable time synchronization in the device that
-generates the codes. For example:
-
-- For Android (Google Authenticator):
- 1. Go to the Main Menu in Google Authenticator.
- 1. Select Settings.
- 1. Select the Time correction for the codes.
- 1. Select Sync now.
-- For iOS:
- 1. Go to Settings.
- 1. Select General.
- 1. Select Date & Time.
- 1. Enable Set Automatically. If it's already enabled, disable it, wait a few seconds, and re-enable.
-
-### Error: "Permission denied (publickey)" when regenerating recovery codes
-
-If you receive a `Permission denied (publickey)` error when attempting to [generate new recovery codes using an SSH key](#generate-new-recovery-codes-using-ssh)
-and you are using a non-default SSH key pair file path,
-you might need to [manually register your private SSH key](../../ssh.md#configure-ssh-to-point-to-a-different-directory) using `ssh-agent`.
diff --git a/doc/user/profile/account/two_factor_authentication_troubleshooting.md b/doc/user/profile/account/two_factor_authentication_troubleshooting.md
new file mode 100644
index 0000000000000..b4293a42983bc
--- /dev/null
+++ b/doc/user/profile/account/two_factor_authentication_troubleshooting.md
@@ -0,0 +1,155 @@
+---
+stage: Govern
+group: Authentication
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
+---
+
+## Troubleshooting two-factor authentication
+
+DETAILS:
+**Tier:** Free, Premium, Ultimate
+**Offering:** GitLab.com, Self-managed
+
+### Error: "HTTP Basic: Access denied. The provided password or token ..."
+
+When making a request, you can receive the following error:
+
+```plaintext
+HTTP Basic: Access denied. The provided password or token is incorrect or your account has 2FA enabled and you must use a personal
+access token instead of a password.
+```
+
+This error occurs in the following scenarios:
+
+- You have 2FA enabled and have attempted to authenticate with a username and
+ password.
+- You do not have 2FA enabled and have sent an incorrect username or password
+ with your request.
+- You do not have 2FA enabled but an administrator has enabled the
+ [enforce 2FA for all users](../../../security/two_factor_authentication.md#enforce-2fa-for-all-users) setting.
+- You do not have 2FA enabled, but an administrator has disabled the
+ [password authentication enabled for Git over HTTP(S)](../../../administration/settings/sign_in_restrictions.md#password-authentication-enabled)
+ setting.
+
+Instead you can authenticate:
+
+- Using a [personal access token](../personal_access_tokens.md) (PAT):
+ - For Git requests over HTTP(S), a PAT with `read_repository` or `write_repository` scope is required.
+ - For [GitLab container registry](../../packages/container_registry/authenticate_with_container_registry.md) requests, a PAT
+ with `read_registry` or `write_registry` scope is required.
+ - For [Dependency Proxy](../../packages/dependency_proxy/index.md#authenticate-with-the-dependency-proxy) requests, a PAT with
+ `read_registry` and `write_registry` scopes is required.
+- If you have configured LDAP, using an [LDAP password](../../../administration/auth/ldap/index.md)
+- Using an [OAuth credential helper](../../profile/account/two_factor_authentication.md#oauth-credential-helpers).
+
+### Error: "invalid pin code"
+
+If you receive an `invalid pin code` error, this can indicate that there is a time sync issue
+between the authentication application and the GitLab instance itself.
+To avoid the time sync issue, enable time synchronization in the device that
+generates the codes. For example:
+
+- For Android (Google Authenticator):
+ 1. Go to the Main Menu in Google Authenticator.
+ 1. Select Settings.
+ 1. Select the Time correction for the codes.
+ 1. Select Sync now.
+- For iOS:
+ 1. Go to Settings.
+ 1. Select General.
+ 1. Select Date & Time.
+ 1. Enable Set Automatically. If it's already enabled, disable it, wait a few seconds, and re-enable.
+
+### Error: "Permission denied (publickey)" when regenerating recovery codes
+
+If you receive a `Permission denied (publickey)` error when attempting to
+[generate new recovery codes using an SSH key](#generate-new-recovery-codes-using-ssh)
+and you are using a non-default SSH key pair file path, you might need to
+[manually register your private SSH key](../../ssh.md#configure-ssh-to-point-to-a-different-directory) using `ssh-agent`.
+
+## Recovery options and 2FA reset
+
+If you don't have access to your code generation device and are unable to sign into your account, the following recovery options are available:
+
+- If you saved your recovery codes when you enabled 2FA, [use a saved recovery code](#use-a-saved-recovery-code).
+- If you don't have your recovery codes but have an SSH key, [generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh).
+- If you don't have your recovery codes or an SSH key, [disable and reset 2FA on your account](#disable-and-reset-2fa-on-your-account)
+
+### Use a saved recovery code
+
+To use a recovery code:
+
+1. Enter your username or email, and password, on the GitLab sign-in page.
+1. When prompted for a two-factor code, enter the recovery code.
+
+After you use a recovery code, you cannot re-use it. You can still use the other recovery codes you saved.
+
+### Generate new recovery codes using SSH
+
+If you forget to save your recovery codes when enabling 2FA, and you added an SSH key to your GitLab account, you can generate a new set of recovery codes with SSH:
+
+1. In a terminal, run:
+
+ ```shell
+ ssh git@gitlab.com 2fa_recovery_codes
+ ```
+
+ On self-managed instances, replace **`gitlab.com`** in the command above with the GitLab server hostname (`gitlab.example.com`).
+
+1. You are prompted to confirm that you want to generate new codes. This process invalidates previously-saved codes. For
+ example:
+
+ ```shell
+ Are you sure you want to generate new two-factor recovery codes?
+ Any existing recovery codes you saved will be invalidated. (yes/no)
+
+ yes
+
+ Your two-factor authentication recovery codes are:
+
+ 119135e5a3ebce8e
+ 11f6v2a498810dcd
+ 3924c7ab2089c902
+ e79a3398bfe4f224
+ 34bd7b74adbc8861
+ f061691d5107df1a
+ 169bf32a18e63e7f
+ b510e7422e81c947
+ 20dbed24c5e74663
+ df9d3b9403b9c9f0
+
+ During sign in, use one of the codes above when prompted for your
+ two-factor code. Then, visit your Profile Settings and add a new device
+ so you do not lose access to your account again.
+ ```
+
+1. Go to the GitLab sign-in page and enter your username or email, and password. When prompted for a
+ two-factor code, enter one of the recovery codes obtained from the command-line output.
+
+After signing in, immediately set up 2FA with a new device.
+
+### Disable and reset 2FA on your account
+
+DETAILS:
+**Tier:** Premium, Ultimate
+**Offering:** GitLab.com
+
+If other methods are unavailable, create a support ticket to request
+a GitLab global administrator to disable 2FA for your account.
+
+This service is only available for accounts that have a GitLab.com subscription. For more information, see our
+[blog post](https://about.gitlab.com/blog/2020/08/04/gitlab-support-no-longer-processing-mfa-resets-for-free-users/).
+
+1. Go to [GitLab Support](https://support.gitlab.com).
+1. Select **Submit a Ticket**.
+1. If possible, sign into your account.
+1. In the issue dropdown list, select **GitLab.com user accounts and login issues**.
+1. Complete the fields in the support form.
+1. Select **Submit**.
+
+Disabling this setting temporarily leaves your account in a less secure state.
+You should sign in and re-enable 2FA as soon as possible.
+
+If you are a top-level Owner of a namespace on a paid plan, you can disable 2FA for enterprise users.
+For more information, see
+[Disable two-factor-authentication](../../enterprise_user/index.md#disable-two-factor-authentication).
diff --git a/spec/features/profiles/two_factor_auths_spec.rb b/spec/features/profiles/two_factor_auths_spec.rb
index bc6f88474a970..e12b634828e1d 100644
--- a/spec/features/profiles/two_factor_auths_spec.rb
+++ b/spec/features/profiles/two_factor_auths_spec.rb
@@ -59,7 +59,7 @@
fill_in 'pin_code', with: '123'
click_button 'Register with two-factor app'
- expect(page).to have_link('Try the troubleshooting steps here.', href: help_page_path('user/profile/account/two_factor_authentication', anchor: 'troubleshooting'))
+ expect(page).to have_link('Try the troubleshooting steps here.', href: help_page_path('user/profile/account/two_factor_authentication_troubleshooting'))
end
end
--
GitLab