diff options
Diffstat (limited to 'doc/security')
26 files changed, 187 insertions, 142 deletions
diff --git a/doc/security/asset_proxy.md b/doc/security/asset_proxy.md index cde377cbb73..16051d22bd6 100644 --- a/doc/security/asset_proxy.md +++ b/doc/security/asset_proxy.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization 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 --- diff --git a/doc/security/crime_vulnerability.md b/doc/security/crime_vulnerability.md index fdf3e5055b0..2c9969ab707 100644 --- a/doc/security/crime_vulnerability.md +++ b/doc/security/crime_vulnerability.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization 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 type: reference diff --git a/doc/security/email_verification.md b/doc/security/email_verification.md index da844e3a2eb..7ebdfc32d2e 100644 --- a/doc/security/email_verification.md +++ b/doc/security/email_verification.md @@ -1,5 +1,5 @@ --- -stage: Anti-Abuse +stage: Govern group: Anti-Abuse 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 --- diff --git a/doc/security/hardening.md b/doc/security/hardening.md index 21b8594fc6e..9c222e5c758 100644 --- a/doc/security/hardening.md +++ b/doc/security/hardening.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Manage +stage: Govern group: Authentication and Authorization 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 --- diff --git a/doc/security/hardening_application_recommendations.md b/doc/security/hardening_application_recommendations.md index e9c09abdea1..5a11c53ffee 100644 --- a/doc/security/hardening_application_recommendations.md +++ b/doc/security/hardening_application_recommendations.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Manage +stage: Govern group: Authentication and Authorization 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 --- @@ -14,7 +14,7 @@ web interface. ## System hooks -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **System Hooks**. @@ -33,7 +33,7 @@ encouraged for communications through system hooks. ## Push rules -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Push Rules**. @@ -48,7 +48,7 @@ The adjustments help limit pushes to established and authorized users. ## Deploy keys -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Deploy Keys**. @@ -61,7 +61,7 @@ the documentation on [deploy keys](../user/project/deploy_keys/index.md) and ## General -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > General**. @@ -180,7 +180,7 @@ For more detailed information, see ## Integrations -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Integrations**. @@ -192,7 +192,7 @@ process or authenticated user. ## Metrics and profiling -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Metrics and profiling**. @@ -206,11 +206,11 @@ security patches come out frequently, this helps you stay up to date. restrict data gathering and statistics reporting to a software vendor, you may have to disable the **Enable service ping** feature. For more information on what data is collected to help you make an informed decision, see -[service ping](../development/service_ping/index.md). +[service ping](../development/internal_analytics/service_ping/index.md). ## Network -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Network**. diff --git a/doc/security/hardening_cicd_recommendations.md b/doc/security/hardening_cicd_recommendations.md index 16b649cbdd7..72a3699868b 100644 --- a/doc/security/hardening_cicd_recommendations.md +++ b/doc/security/hardening_cicd_recommendations.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Manage +stage: Govern group: Authentication and Authorization 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 --- diff --git a/doc/security/hardening_configuration_recommendations.md b/doc/security/hardening_configuration_recommendations.md index 1cc3294f68b..e8cae41c535 100644 --- a/doc/security/hardening_configuration_recommendations.md +++ b/doc/security/hardening_configuration_recommendations.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Manage +stage: Govern group: Authentication and Authorization 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 --- diff --git a/doc/security/hardening_general_concepts.md b/doc/security/hardening_general_concepts.md index a227f0134d0..3c50196f9bc 100644 --- a/doc/security/hardening_general_concepts.md +++ b/doc/security/hardening_general_concepts.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Manage +stage: Govern group: Authentication and Authorization 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 --- diff --git a/doc/security/hardening_operating_system_recommendations.md b/doc/security/hardening_operating_system_recommendations.md index 33f88d43d22..80eea9b5085 100644 --- a/doc/security/hardening_operating_system_recommendations.md +++ b/doc/security/hardening_operating_system_recommendations.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Manage +stage: Govern group: Authentication and Authorization 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 --- diff --git a/doc/security/identity_verification.md b/doc/security/identity_verification.md index a4f7baad0e2..b6932d88820 100644 --- a/doc/security/identity_verification.md +++ b/doc/security/identity_verification.md @@ -1,5 +1,5 @@ --- -stage: Anti-Abuse +stage: Govern group: Anti-Abuse 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 --- diff --git a/doc/security/index.md b/doc/security/index.md index 5365228537f..d3bff521fcb 100644 --- a/doc/security/index.md +++ b/doc/security/index.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization 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 type: index @@ -24,7 +24,7 @@ type: index - [Proxying images](asset_proxy.md) - [CI/CD variables](../ci/variables/index.md#cicd-variable-security) - [Token overview](token_overview.md) -- [Maximum decompressed file size for imported archives](../administration/settings/account_and_limit_settings.md#maximum-decompressed-file-size-for-imported-archives) +- [Maximum decompressed file size for imported archives](../administration/settings/import_and_export_settings.md#maximum-decompressed-file-size-for-imported-archives) - [Responding to security incidents](responding_to_security_incidents.md) To harden your GitLab instance and minimize the risk of unwanted user account creation, consider access control features like [Sign up restrictions](../administration/settings/sign_up_restrictions.md) and [Authentication options](../topics/authentication/index.md). For more detailed information, refer to [Hardening](hardening.md). diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md index 21e4ad8b108..a0d7b425a23 100644 --- a/doc/security/information_exclusivity.md +++ b/doc/security/information_exclusivity.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization 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 type: concepts diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md index d8e9728f455..c7ebd713240 100644 --- a/doc/security/password_length_limits.md +++ b/doc/security/password_length_limits.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization 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 type: reference, howto @@ -24,7 +24,7 @@ The user password length is set to a minimum of 8 characters by default. To change the minimum password length using GitLab UI: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Sign-up restrictions**. diff --git a/doc/security/password_storage.md b/doc/security/password_storage.md index e814f4e5069..71e7510513e 100644 --- a/doc/security/password_storage.md +++ b/doc/security/password_storage.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization 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 type: reference diff --git a/doc/security/passwords_for_integrated_authentication_methods.md b/doc/security/passwords_for_integrated_authentication_methods.md index a141241f97c..c7d94120887 100644 --- a/doc/security/passwords_for_integrated_authentication_methods.md +++ b/doc/security/passwords_for_integrated_authentication_methods.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization 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 type: reference diff --git a/doc/security/project_import_decompressed_archive_size_limits.md b/doc/security/project_import_decompressed_archive_size_limits.md index 48767740625..a4749d0e5f9 100644 --- a/doc/security/project_import_decompressed_archive_size_limits.md +++ b/doc/security/project_import_decompressed_archive_size_limits.md @@ -1,9 +1,9 @@ --- -redirect_to: '../administration/settings/account_and_limit_settings.md#maximum-decompressed-file-size-for-imported-archives' +redirect_to: '../administration/settings/import_and_export_settings.md#maximum-decompressed-file-size-for-imported-archives' remove_date: '2023-11-02' --- -This document was moved to [another location](../administration/settings/account_and_limit_settings.md#maximum-decompressed-file-size-for-imported-archives). +This document was moved to [another location](../administration/settings/import_and_export_settings.md#maximum-decompressed-file-size-for-imported-archives). <!-- This redirect file can be deleted after <2023-11-02>. --> <!-- Redirects that point to other docs in the same project expire in three months. --> diff --git a/doc/security/rate_limits.md b/doc/security/rate_limits.md index ee10d66a8ad..936e2931ff5 100644 --- a/doc/security/rate_limits.md +++ b/doc/security/rate_limits.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization 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 type: reference, howto @@ -121,6 +121,9 @@ The **rate limit** is 20 calls per minute per IP address. ### Project Jobs API endpoint +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382985) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `ci_enforce_rate_limits_jobs_api`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/384186) in GitLab 16.0. Feature flag `ci_enforce_rate_limits_jobs_api` removed. + There is a rate limit for the endpoint `project/:id/jobs`, which is enforced to reduce timeouts when retrieving jobs. The **rate limit** is 600 calls per minute per authenticated user. @@ -186,7 +189,7 @@ To remove a blocked IP: keys *rack::attack* ``` -By default, the [`keys` command is disabled](https://docs.gitlab.com/omnibus/settings/redis.html#renamed-commands). + By default, the [`keys` command is disabled](https://docs.gitlab.com/omnibus/settings/redis.html#renamed-commands). 1. Optionally, add [the IP to the allowlist](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-rack-attack) to prevent it being denylisted again. diff --git a/doc/security/reset_user_password.md b/doc/security/reset_user_password.md index fa15efe7cb7..4a59d2f9a21 100644 --- a/doc/security/reset_user_password.md +++ b/doc/security/reset_user_password.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization 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 type: howto @@ -20,7 +20,7 @@ The user's new password must meet all [password requirements](../user/profile/us To reset a user's password in the UI: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Overview > Users**. 1. For the user whose password you want to update, select **Edit**. diff --git a/doc/security/responding_to_security_incidents.md b/doc/security/responding_to_security_incidents.md index 0cd7170d35b..b5e38ce55ca 100644 --- a/doc/security/responding_to_security_incidents.md +++ b/doc/security/responding_to_security_incidents.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization 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 type: reference, howto diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md index 87cbf12471f..90affd089f3 100644 --- a/doc/security/ssh_keys_restrictions.md +++ b/doc/security/ssh_keys_restrictions.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Manage +stage: Govern group: Authentication and Authorization 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 --- @@ -20,7 +20,7 @@ limit the allowed SSH key algorithms. GitLab allows you to restrict the allowed SSH key technology as well as specify the minimum key length for each technology: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +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 **Visibility and access controls** section: diff --git a/doc/security/token_overview.md b/doc/security/token_overview.md index cb01c7d5160..f605e95dfbf 100644 --- a/doc/security/token_overview.md +++ b/doc/security/token_overview.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization 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 type: reference @@ -20,9 +20,10 @@ You can create [Personal access tokens](../user/profile/personal_access_tokens.m You can limit the scope and expiration date of your personal access tokens. By default, they inherit permissions from the user who created them. -You can use the [personal access tokens API](../api/personal_access_tokens.md) to -programmatically take action, such as -[rotating a personal access token](../api/personal_access_tokens.md#rotate-a-personal-access-token). +You can use the personal access tokens API to programmatically take action, +such as [rotating a personal access token](../api/personal_access_tokens.md#rotate-a-personal-access-token). + +You will receive an email when personal access tokens are 7 days or less from expiration. ## OAuth2 tokens @@ -55,6 +56,8 @@ You can use the [project access tokens API](../api/project_access_tokens.md) to programmatically take action, such as [rotating a project access token](../api/project_access_tokens.md#rotate-a-project-access-token). +All project maintainers receive an email when project access tokens are 7 days or less from expiration. + ## Group access tokens [Group access tokens](../user/group/settings/group_access_tokens.md#group-access-tokens) @@ -72,6 +75,8 @@ You can use the [group access tokens API](../api/group_access_tokens.md) to programmatically take action, such as [rotating a group access token](../api/group_access_tokens.md#rotate-a-group-access-token). +All group owners receive an email when group access tokens are 7 days or less from expiration. + ## Deploy tokens [Deploy tokens](../user/project/deploy_tokens/index.md) allow you to download (`git clone`) or push and pull packages and container registry images of a project without having a user and a password. Deploy tokens cannot be used with the GitLab API. @@ -86,39 +91,50 @@ This is useful, for example, for cloning repositories to your Continuous Integra Project maintainers and owners can add or enable a deploy key for a project repository -## Runner registration tokens (deprecated) +## Runner authentication tokens -WARNING: -The ability to pass a runner registration token has been [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) and is -planned for removal in 17.0, along with support for certain configuration arguments. This change is a breaking change. GitLab plans to introduce a new -[GitLab Runner token architecture](../architecture/blueprints/runner_tokens/index.md), which introduces -a new method for registering runners and eliminates the -runner registration token. +In GitLab 16.0 and later, you can use a runner authentication token to register +runners instead of a runner registration token. Runner registration tokens have +been [deprecated](../update/deprecations.md#registration-tokens-and-server-side-runner-arguments-in-gitlab-runner-register-command). -Runner registration tokens are used to [register](https://docs.gitlab.com/runner/register/) a [runner](https://docs.gitlab.com/runner/) with GitLab. Group or project owners or instance administrators can obtain them through the GitLab user interface. The registration token is limited to runner registration and has no further scope. +After you create a runner and its configuration, you receive a runner authentication token +that you use to register the runner. The runner authentication token is stored locally in the +[`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) file, which +you use to configure the runner. -You can use the runner registration token to add runners that execute jobs in a project or group. The runner has access to the project's code, so be careful when assigning project and group-level permissions. +The runner uses the runner authentication token to authenticate with GitLab when +it picks up jobs from the job queue. After the runner authenticates with GitLab, +the runner receives a [job token](../ci/jobs/ci_job_token.md), which it uses to +execute the job. -## Runner authentication tokens (also called runner tokens) +The runner authentication token stays on the runner machine. The execution environments +for the following executors only have access to the job token and not the runner authentication token: -Once created, the runner receives an authentication token, which it uses to authenticate with GitLab when picking up jobs from the job queue. The authentication token is stored locally in the runner's [`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) file. +- Docker Machine +- Kubernetes +- VirtualBox +- Parallels +- SSH -After authentication with GitLab, the runner receives a [job token](../ci/jobs/ci_job_token.md), which it uses to execute the job. +Malicious access to a runner's file system may expose the `config.toml` file and the +runner authentication token. The attacker could use the runner authentication +to [clone the runner](https://docs.gitlab.com/runner/security/#cloning-a-runner). -In case of Docker Machine/Kubernetes/VirtualBox/Parallels/SSH executors, the execution environment has no access to the runner authentication token, because it stays on the runner machine. They have access to the job token only, which is needed to execute the job. +You can use the `runners` API to +programmatically [rotate or revoke a runner authentication token](../api/runners.md#reset-runners-authentication-token-by-using-the-current-token). -Malicious access to a runner's file system may expose the `config.toml` file and thus the authentication token, allowing an attacker to [clone the runner](https://docs.gitlab.com/runner/security/#cloning-a-runner). +## Runner registration tokens (deprecated) -In GitLab 16.0 and later, you can use an authentication token to register runners instead of a -registration token. Runner registration tokens have been [deprecated](../update/deprecations.md#registration-tokens-and-server-side-runner-arguments-in-gitlab-runner-register-command). +WARNING: +The ability to pass a runner registration token has been [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) and is +planned for removal in GitLab 18.0, along with support for certain configuration arguments. This change is a breaking change. GitLab has implemented a new +[GitLab Runner token architecture](../ci/runners/new_creation_workflow.md), which introduces +a new method for registering runners and eliminates the +runner registration token. -To generate an authentication token, you create a runner in the GitLab UI and use the authentication token -instead of the registration token. +Runner registration tokens are used to [register](https://docs.gitlab.com/runner/register/) a [runner](https://docs.gitlab.com/runner/) with GitLab. Group or project owners or instance administrators can obtain them through the GitLab user interface. The registration token is limited to runner registration and has no further scope. -| Process | Registration command | -| ------------------ | --------------------- | -| Registration token (deprecated) | `gitlab-runner register --registration-token $RUNNER_REGISTRATION_TOKEN <runner configuration arguments>` | -| Authentication token | `gitlab-runner register --token $RUNNER_AUTHENTICATION_TOKEN` | +You can use the runner registration token to add runners that execute jobs in a project or group. The runner has access to the project's code, so be careful when assigning project and group-level permissions. ## CI/CD job tokens diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index 906bf4cd062..0c569e9843d 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -1,50 +1,55 @@ --- type: howto -stage: Manage +stage: Govern group: Authentication and Authorization 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) 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. +[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. -Read more about [two-factor authentication (2FA)](../user/profile/account/two_factor_authentication.md). - ## Enforce 2FA for all users **(FREE SELF)** -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: +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. -- 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`. -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. -To enable 2FA for all users: +### Use the UI -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +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, where you can configure both. +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`. -If you want 2FA enforcement to take effect during the next sign-in attempt, -change the grace period to `0`. +### Use the API -### Disable 2FA enforcement through Rails console +Use the [application settings API](../api/settings.md) to modify the following settings: -Using the [Rails console](../administration/operations/rails_console.md), enforcing 2FA for -all user can be disabled. Connect to the Rails console and run: +- `require_two_factor_authentication`. +- `two_factor_grace_period`. -```ruby -Gitlab::CurrentSettings.update!('require_two_factor_authentication': false) -``` +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)** @@ -56,59 +61,67 @@ Prerequisites: To enforce 2FA only for certain groups: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +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**. -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](../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/access_and_permissions.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 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. 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. -- 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. +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. -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, you should use the [API endpoint](../api/users.md#disable-two-factor-authentication) -instead of the Rails console. -Using the [Rails console](../administration/operations/rails_console.md), 2FA for a single user can be disabled. -Connect to the Rails console and run: +#### Administrators -**In GitLab 13.5 and later:** +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>') @@ -117,20 +130,33 @@ user_to_disable = User.find_by_username('<USERNAME>') TwoFactor::DestroyService.new(admin, user: user_to_disable).execute ``` -The target user is notified that 2FA has been disabled. +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 -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: +To disable 2FA for all users even when forced 2FA is disabled, use the following Rake task. -```shell -# Omnibus installations -sudo gitlab-rake gitlab:two_factor:disable_for_all_users +- For installations that use the Linux package: -# Installations from source -sudo -u git -H bundle exec rake gitlab:two_factor:disable_for_all_users RAILS_ENV=production -``` + ```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)** diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md index 5e21cad8f3e..b2c8624b057 100644 --- a/doc/security/unlock_user.md +++ b/doc/security/unlock_user.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization 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 type: howto @@ -25,7 +25,7 @@ If 2FA is enabled, users are locked after five failed sign-in attempts within 10 ## Unlock a user from the Admin Area -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Overview > Users**. 1. Use the search bar to find the locked user. @@ -46,13 +46,13 @@ To unlock a locked user: sudo -u git -H bundle exec rails console -e production ``` -1. Find the user to unlock. You can search by email or ID. +1. Find the user to unlock. You can search by email: ```ruby user = User.find_by(email: 'admin@local.host') ``` - or + Or you can search by ID: ```ruby user = User.where(id: 1).first @@ -64,7 +64,7 @@ To unlock a locked user: user.unlock_access! ``` -1. Exit the console with <kbd>Control</kbd>+<kbd>d</kbd> +1. Exit the console with <kbd>Control</kbd>+<kbd>d</kbd>. The user should now be able to sign in. diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md index 899fed0b584..56445903d6c 100644 --- a/doc/security/user_email_confirmation.md +++ b/doc/security/user_email_confirmation.md @@ -1,6 +1,6 @@ --- type: howto -stage: Manage +stage: Govern group: Authentication and Authorization 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 --- @@ -11,7 +11,7 @@ GitLab can be configured to require confirmation of a user's email address when the user signs up. When this setting is enabled, the user is unable to sign in until they confirm their email address. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Sign-up restrictions** and look for the **Email confirmation settings** options. diff --git a/doc/security/user_file_uploads.md b/doc/security/user_file_uploads.md index e0f1342b9c9..6ddda281a03 100644 --- a/doc/security/user_file_uploads.md +++ b/doc/security/user_file_uploads.md @@ -1,6 +1,6 @@ --- type: reference -stage: Manage +stage: Govern group: Authentication and Authorization 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 --- @@ -47,7 +47,7 @@ Prerequisite: To configure authentication settings for all media files: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Scroll to **Project visibility** and select **Require authentication to view media files**. diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md index 78c32341bf6..f8bd50bc4b3 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization 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 type: concepts, reference, howto @@ -50,7 +50,7 @@ To prevent exploitation of insecure internal web services, all webhook and integ To allow access to these addresses: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Outbound requests**. @@ -64,7 +64,7 @@ Prerequisite: [System hooks](../administration/system_hooks.md) can make requests to the local network by default. To prevent system hook requests to the local network: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Outbound requests**. @@ -80,7 +80,7 @@ Prerequisite: To filter requests by blocking many requests: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Outbound requests**. @@ -106,7 +106,7 @@ Prerequisite: To allow outbound requests to certain IP addresses and domains: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Outbound requests**. |