1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
---
type: howto
stage: Govern
group: Authentication
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Enforce two-factor authentication **(FREE ALL)**
[Two-factor authentication (2FA)](../user/profile/account/two_factor_authentication.md)
is an authentication method that requires the user to provide two different factors
to prove their identity:
- Username and password.
- A second authentication method, such as a code generated by an application.
2FA makes it harder for an unauthorized person to access an account because
they would need both factors.
NOTE:
If you are [using and enforcing SSO](../user/group/saml_sso/index.md#sso-enforcement), you might already be enforcing 2FA on the identity provider (IDP) side. Enforcing 2FA on GitLab as well might be unnecessary.
## Enforce 2FA for all users **(FREE SELF)**
Administrators can enforce 2FA for all users in two different ways:
- Enforce on next sign in.
- Suggest on next sign in, but allow a grace period before enforcing.
After the configured grace period has elapsed, users can sign in but
cannot leave the 2FA configuration area at `/-/profile/two_factor_auth`.
You can use the UI or the API to enforce 2FA for all users.
### Use the UI
1. On the left sidebar, select **Search or go to**.
1. Select **Admin Area**.
1. On the left sidebar, select **Settings > General**.
1. Expand the **Sign-in restrictions** section:
- Select **Enforce two-factor authentication** to enable this feature.
- In **Two-factor grace period**, enter a number of hours. If you want to
enforce 2FA on next sign-in attempt, enter `0`.
### Use the API
Use the [application settings API](../api/settings.md) to modify the following settings:
- `require_two_factor_authentication`.
- `two_factor_grace_period`.
For more information, see the [list of settings that can be accessed through API calls](../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls).
## Enforce 2FA for all users in a group **(FREE ALL)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24965) in GitLab 12.0, 2FA settings for a group are also applied to subgroups.
Prerequisites:
- You must have the Maintainer or Owner role for the group.
To enforce 2FA only for certain groups:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Settings > General**.
1. Expand **Permissions and group features**.
1. Select **All users in this group must set up two-factor authentication**.
1. Optional. In **Delay 2FA enforcement (hours)**, enter the number of hours you
want the grace period to last for.
If there are multiple different grace periods in a top level group and its subgroups
and projects, the shortest grace period is used.
1. Select **Save changes**.
Enforcement affects all [direct and inherited members](../user/project/members/index.md#membership-types) in the group.
Access tokens are not required to provide a second factor for authentication because
they are API-based. Tokens generated before 2FA is enforced remain valid.
### 2FA in subgroups
You can enable and enforce 2FA for individual subgroups in the same way as a top
level group.
You can prevent subgroups from setting up their own 2FA requirements:
1. Go to the top level group's **Settings > General**.
1. Expand the **Permissions and group features** section.
1. Clear the **Allow subgroups to set up their own two-factor authentication rule** checkbox.
This action causes all subgroups with 2FA requirements to stop requiring 2FA from
their members.
### 2FA in projects
If a project belonging to a group that enables or enforces 2FA is [shared](../user/project/members/share_project_with_groups.md)
with a group that does not enable or enforce 2FA, members of the non-2FA group can access that project
without using 2FA. For example:
- Group *A* has 2FA enabled and enforced. Group *B* does not have 2FA enabled.
- If a project, *P*, that belongs to group *A* is shared with group *B*, members
of group *B* can access project *P* without 2FA.
To ensure this does not occur, [prevent sharing of projects](../user/group/access_and_permissions.md#prevent-a-project-from-being-shared-with-groups)
for the 2FA group.
If you add members to a project in a group or subgroup that has 2FA
enabled, 2FA is **not** required for those individually added members.
## Disable 2FA **(FREE SELF)**
You can disable 2FA for a single user or all users.
This is a permanent and irreversible action. Users must reactivate 2FA to use it again.
WARNING:
Disabling 2FA for users does not disable the [enforce 2FA for all users](#enforce-2fa-for-all-users)
or [enforce 2FA for all users in a group](#enforce-2fa-for-all-users-in-a-group)
settings. You must also disable any enforced 2FA settings so users aren't asked to set up 2FA again
when they next sign in to GitLab.
### For a single user
#### Administrators
In GitLab 13.5 and later, use the [Rails console](../administration/operations/rails_console.md)
to disable 2FA for a single administrator:
```ruby
admin = User.find_by_username('<USERNAME>')
user_to_disable = User.find_by_username('<USERNAME>')
TwoFactor::DestroyService.new(admin, user: user_to_disable).execute
```
The administrator is notified that 2FA has been disabled.
#### Non-administrators
In GitLab 15.2 and later, you can use either the Rails console or the
[API endpoint](../api/users.md#disable-two-factor-authentication) to disable 2FA
for a non-administrator.
You can disable 2FA for your own account.
You cannot use the API endpoint to disable 2FA for administrators.
### For all users
To disable 2FA for all users even when forced 2FA is disabled, use the following Rake task.
- For installations that use the Linux package:
```shell
sudo gitlab-rake gitlab:two_factor:disable_for_all_users
```
- For self-compiled installations:
```shell
sudo -u git -H bundle exec rake gitlab:two_factor:disable_for_all_users RAILS_ENV=production
```
## 2FA for Git over SSH operations **(PREMIUM ALL)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/270554) in GitLab 13.7.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/299088) from GitLab Free to GitLab Premium in 13.9.
> - It's deployed behind a feature flag, disabled by default.
> - Push notification support [introduced](https://gitlab.com/gitlab-org/gitlab-shell/-/issues/506) in GitLab 15.3.
FLAG:
On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) named `two_factor_for_cli`. On GitLab.com, this feature is not available. The feature is not ready for production use. This feature flag also affects [session duration for Git Operations when 2FA is enabled](../administration/settings/account_and_limit_settings.md#customize-session-duration-for-git-operations-when-2fa-is-enabled).
You can enforce 2FA for [Git over SSH operations](../development/gitlab_shell/features.md#git-operations). However, you should use
[ED25519_SK](../user/ssh.md#ed25519_sk-ssh-keys) or [ECDSA_SK](../user/ssh.md#ecdsa_sk-ssh-keys) SSH keys instead. 2FA is enforced for Git operations only, and internal commands such as [`personal_access_token`](../development/gitlab_shell/features.md#personal-access-token) are excluded.
To perform one-time password (OTP) verification, run:
```shell
ssh git@<hostname> 2fa_verify
```
Then authenticate by either:
- Entering the correct OTP.
- In GitLab 15.3 and later, responding to a device push notification if
[FortiAuthenticator is enabled](../user/profile/account/two_factor_authentication.md#enable-one-time-password-using-fortiauthenticator).
After successful authentication, you can perform [Git over SSH operations](../development/gitlab_shell/features.md#git-operations) for 15 minutes (default) with the associated
SSH key.
### Security limitation
2FA does not protect users with compromised *private* SSH keys.
Once an OTP is verified, anyone can run Git over SSH with that private SSH key for
the configured [session duration](../administration/settings/account_and_limit_settings.md#customize-session-duration-for-git-operations-when-2fa-is-enabled).
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, for example `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
|
