debian-mirror-gitlab/doc/security/two_factor_authentication.md

---
type: howto
stage: Manage
group: Access
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---

# Enforce Two-factor Authentication (2FA)

Two-factor Authentication (2FA) provides an additional level of security to your
users' GitLab account. After being enabled, in addition to supplying their
username and password to sign in, they are prompted for a code generated by an
application on their phone.

You can read more about it here:
[Two-factor Authentication (2FA)](../user/profile/account/two_factor_authentication.md)

## Enforcing 2FA for all users

Users on GitLab can enable it without any administrator's intervention. If you
want to enforce everyone to set up 2FA, you can choose from two different ways:

- Enforce on next login.
- Suggest on next login, 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`.

To enable 2FA for all users:

1. On the top bar, select **Menu >** **{admin}** **Admin**.
1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`).
1. Expand the **Sign-in restrictions** section, where you can configure both.

If you want 2FA enforcement to take effect during the next sign-in attempt,
change the grace period to `0`.

## Enforcing 2FA for all users in a group

> [Introduced in](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24965) GitLab 12.0, 2FA settings for a group are also applied to subgroups.

If you want to enforce 2FA only for certain groups:

1. Go to the group's **Settings > General** page.
1. Expand the **Permissions, LFS, 2FA** section.
1. Select the **Require all users in this group to setup two-factor authentication** option.

You can also specify a grace period in the **Time before enforced** option.

To change this setting, you need to be administrator or owner of the group.

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
  [is shared](../user/project/members/share_project_with_groups.md)
  with a 2FA-disabled group will *not* require members of the 2FA-disabled group to use
  2FA for the project. For example, if project *P* belongs to 2FA-enabled group *A* and
  is shared with 2FA-disabled group *B*, members of group *B* can access project *P*
  without 2FA. To ensure this scenario doesn't occur,
  [prevent sharing of projects](../user/group/index.md#prevent-a-project-from-being-shared-with-groups)
  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 is used.
- It is possible to disallow subgroups from setting up their own 2FA requirements:
  1. Go to the top-level group's **Settings > General**.
  1. Expand the **Permissions, LFS, 2FA** section.
  1. Uncheck the **Allow subgroups to set up their own two-factor authentication rule** field.

  This action causes all subgroups with 2FA requirements to stop requiring that from their members.

## Disabling 2FA for everyone

WARNING:
Disabling 2FA for everyone does not disable the [enforce 2FA for all users](#enforcing-2fa-for-all-users)
or [enforce 2FA for all users in a group](#enforcing-2fa-for-all-users-in-a-group)
settings. In addition to the steps in this section, you must disable any enforced 2FA
settings so users aren't asked to set up 2FA again, the next time the user signs in to GitLab.

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:

```shell
# Omnibus installations
sudo gitlab-rake gitlab:two_factor:disable_for_all_users

# Installations from source
sudo -u git -H bundle exec rake gitlab:two_factor:disable_for_all_users RAILS_ENV=production
```

WARNING:
This is a permanent and irreversible action. Users have to
reactivate 2FA from scratch if they want to use it again.

## Two-factor Authentication (2FA) for Git over SSH operations **(PREMIUM)**

> - [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](../user/feature_flags.md), disabled by default.
> - It's disabled on GitLab.com.
> - It's not recommended for production use.
> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-two-factor-authentication-2fa-for-git-operations).

WARNING:
This feature might not be available to you. Check the **version history** note above for details.

Two-factor authentication can be enforced for Git over SSH operations. The OTP
verification can be done via a GitLab Shell command:

```shell
ssh git@<hostname> 2fa_verify
```

Once the OTP is verified, Git over SSH operations can be used for a session duration of
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](../user/admin_area/settings/account_and_limit_settings.md#customize-session-duration-for-git-operations-when-2fa-is-enabled).

### Enable or disable Two-factor Authentication (2FA) for Git operations

Two-factor Authentication (2FA) for Git operations is under development and not
ready for production use. It is deployed behind a feature flag that is
**disabled by default**. [GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md)
can enable it.

To enable it:

```ruby
Feature.enable(:two_factor_for_cli)
```

To disable it:

```ruby
Feature.disable(:two_factor_for_cli)
```

The feature flag affects these features:

- [Two-factor Authentication (2FA) for Git over SSH operations](#two-factor-authentication-2fa-for-git-over-ssh-operations).
- [Customize session duration for Git Operations when 2FA is enabled](../user/admin_area/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, 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. -->