gitlab-org--gitlab-foss/doc/security/two_factor_authentication.md

type	stage	group	info
howto	Manage	Authentication and Authorization	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 (FREE SELF)

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

Read more about two-factor authentication (2FA)

Enforce 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.
2. On the left sidebar, select Settings > General (/admin/application_settings/general).
3. 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.

Disable 2FA enforcement through Rails console

Using the Rails console, enforcing 2FA for all user can be disabled. Connect to the Rails console and run:

Gitlab::CurrentSettings.update!('require_two_factor_authentication': false)

Enforce 2FA for all users in a group (FREE)

Introduced 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 top bar, select Menu > Groups and find your group.
2. On the left sidebar, select Settings > General.
3. Expand Permissions and group features.
4. Select All users in this group must set up two-factor authentication.
5. Select Save changes.

You can also specify a grace period in the Delay 2FA enforcement option.

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.

The following are important notes about 2FA:

• Projects belonging to a 2FA-enabled group that is shared 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 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 prevent subgroups from setting up their own 2FA requirements:

  1. Go to the top-level group's Settings > General.
  2. Expand the Permissions and group features section.
  3. 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.

Disable 2FA

WARNING: Disabling 2FA for users does not disable the enforce 2FA for all users or 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.

WARNING: This is a permanent and irreversible action. Users must reactivate 2FA to use it again.

For a single user

To disable 2FA for non-administrator users, we recommend using the API endpoint instead of the Rails console. Using the Rails console, 2FA for a single user can be disabled. Connect to the Rails console and run:

admin = User.find_by_username('<USERNAME>')
user_to_disable = User.find_by_username('<USERNAME>')

TwoFactor::DestroyService.new(admin, user: user_to_disable).execute

For all users

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:

# 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

2FA for Git over SSH operations (PREMIUM)

• Introduced in GitLab 13.7.
• Moved from GitLab Free to GitLab Premium in 13.9.
• It's deployed behind a feature flag, disabled by default.

FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to enable the feature flag 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.

Two-factor authentication can be enforced for Git over SSH operations. However, we recommend using ED25519_SK or ECDSA_SK SSH keys instead.

The one-time password (OTP) verification can be done using a command:

ssh git@<hostname> 2fa_verify

After 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.