2019-06-07 10:33:31 -04:00
|
|
|
---
|
|
|
|
type: howto
|
|
|
|
---
|
2019-07-16 03:02:20 -04:00
|
|
|
|
2015-12-24 15:58:46 -05:00
|
|
|
# Enforce Two-factor Authentication (2FA)
|
|
|
|
|
|
|
|
Two-factor Authentication (2FA) provides an additional level of security to your
|
|
|
|
users' GitLab account. Once enabled, in addition to supplying their username and
|
|
|
|
password to login, they'll be prompted for a code generated by an application on
|
|
|
|
their phone.
|
|
|
|
|
|
|
|
You can read more about it here:
|
2018-12-03 19:01:47 -05:00
|
|
|
[Two-factor Authentication (2FA)](../user/profile/account/two_factor_authentication.md)
|
2015-12-24 15:58:46 -05:00
|
|
|
|
2017-01-24 16:09:58 -05:00
|
|
|
## Enforcing 2FA for all users
|
2015-12-24 15:58:46 -05:00
|
|
|
|
|
|
|
Users on GitLab, can enable it without any admin's intervention. If you want to
|
2018-09-19 12:03:00 -04:00
|
|
|
enforce everyone to set up 2FA, you can choose from two different ways:
|
2015-12-24 15:58:46 -05:00
|
|
|
|
2018-11-12 19:39:21 -05:00
|
|
|
- Enforce on next login.
|
|
|
|
- Suggest on next login, but allow a grace period before enforcing.
|
2015-12-24 15:58:46 -05:00
|
|
|
|
2019-06-05 15:20:26 -04:00
|
|
|
After the configured grace period has elapsed, users will be able to log in but
|
|
|
|
won't be able to leave the 2FA configuration area at `/profile/two_factor_auth`.
|
|
|
|
|
|
|
|
To enable 2FA for all users:
|
|
|
|
|
2020-01-08 19:07:40 -05:00
|
|
|
1. Navigate to **Admin Area > Settings > General** (`/admin/application_settings`).
|
2019-06-05 15:20:26 -04:00
|
|
|
1. Expand the **Sign-in restrictions** section, where you can configure both.
|
2015-12-24 15:58:46 -05:00
|
|
|
|
|
|
|
If you want 2FA enforcement to take effect on next login, change the grace
|
2016-01-22 04:23:32 -05:00
|
|
|
period to `0`.
|
|
|
|
|
2019-06-05 15:20:26 -04:00
|
|
|
## Enforcing 2FA for all users in a group
|
2016-01-22 04:23:32 -05:00
|
|
|
|
2019-06-05 15:20:26 -04:00
|
|
|
If you want to enforce 2FA only for certain groups, you can:
|
2015-12-24 15:58:46 -05:00
|
|
|
|
2019-06-05 15:20:26 -04:00
|
|
|
1. Enable it in the group's **Settings > General** page.
|
|
|
|
1. Optionally specify a grace period as above.
|
2017-01-24 16:09:58 -05:00
|
|
|
|
2019-06-05 15:20:26 -04:00
|
|
|
To change this setting, you need to be administrator or owner of the group.
|
2017-01-24 16:09:58 -05:00
|
|
|
|
2019-09-18 10:02:45 -04:00
|
|
|
> [From](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/24965) GitLab 12.0, 2FA settings for a group are also applied to subgroups.
|
2019-06-03 00:15:53 -04:00
|
|
|
|
|
|
|
If you want to enforce 2FA only for certain groups, you can enable it in the
|
|
|
|
group settings and specify a grace period as above. To change this setting you
|
|
|
|
need to be administrator or owner of the group.
|
|
|
|
|
|
|
|
The following are important notes about 2FA:
|
|
|
|
|
|
|
|
- Projects belonging to a 2FA-enabled group that
|
2019-07-14 20:46:34 -04:00
|
|
|
[is shared](../user/project/members/share_project_with_groups.md)
|
2019-06-03 00:15:53 -04:00
|
|
|
with a 2FA-disabled group will *not* require members of the 2FA-disabled group to use
|
2019-07-14 20:46:34 -04:00
|
|
|
2FA for the project. For example, if project *P* belongs to 2FA-enabled group *A* and
|
2019-06-03 00:15:53 -04:00
|
|
|
is shared with 2FA-disabled group *B*, members of group *B* can access project *P*
|
2019-07-14 20:46:34 -04:00
|
|
|
without 2FA. To ensure this scenario doesn't occur,
|
2019-06-03 00:15:53 -04:00
|
|
|
[prevent sharing of projects](../user/group/index.md#share-with-group-lock)
|
|
|
|
for the 2FA-enabled group.
|
|
|
|
- If you add additional members to a project within a group or subgroup that has
|
|
|
|
2FA enabled, 2FA is **not** required for those individually added members.
|
|
|
|
- If there are multiple 2FA requirements (for example, group + all users, or multiple
|
|
|
|
groups) the shortest grace period will be used.
|
2017-01-24 16:09:58 -05:00
|
|
|
|
2015-12-24 15:58:46 -05:00
|
|
|
## Disabling 2FA for everyone
|
|
|
|
|
|
|
|
There may be some special situations where you want to disable 2FA for everyone
|
|
|
|
even when forced 2FA is disabled. There is a rake task for that:
|
|
|
|
|
2019-06-05 15:20:26 -04:00
|
|
|
```sh
|
2016-01-22 04:23:32 -05:00
|
|
|
# Omnibus installations
|
2015-12-24 15:58:46 -05:00
|
|
|
sudo gitlab-rake gitlab:two_factor:disable_for_all_users
|
|
|
|
|
2016-01-22 04:23:32 -05:00
|
|
|
# Installations from source
|
2015-12-24 15:58:46 -05:00
|
|
|
sudo -u git -H bundle exec rake gitlab:two_factor:disable_for_all_users RAILS_ENV=production
|
|
|
|
```
|
|
|
|
|
2019-06-05 15:20:26 -04:00
|
|
|
CAUTION: **Caution:**
|
|
|
|
This is a permanent and irreversible action. Users will have to
|
|
|
|
reactivate 2FA from scratch if they want to use it again.
|
2019-06-07 10:33:31 -04:00
|
|
|
|
|
|
|
<!-- ## 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, e.g. `### 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. -->
|