Add latest changes from gitlab-org/gitlab@13-10-stable-eev13.10.0-rc40

3 files changed, 119 insertions, 3 deletions

diff --git a/doc/security/README.md b/doc/security/README.md
index b009fe5c8da..9b9d4f030ac 100644
--- a/doc/security/README.md
+++ b/doc/security/README.md
@@ -24,6 +24,7 @@ type: index
 - [Security of running jobs](https://docs.gitlab.com/runner/security/)
 - [Proxying images](asset_proxy.md)
 - [CI/CD variables](cicd_variables.md)
+- [Token overview](token_overview.md)
 
 ## Securing your GitLab installation
 
diff --git a/doc/security/token_overview.md b/doc/security/token_overview.md
new file mode 100644
index 00000000000..2bb4ffa8eec
--- /dev/null
+++ b/doc/security/token_overview.md
@@ -0,0 +1,108 @@
+---
+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
+type: reference
+---
+
+# GitLab Token overview
+
+This document lists tokens used in GitLab, their purpose and, where applicable, security guidance.
+
+## Personal access tokens
+
+You can create [Personal access tokens](../user/profile/personal_access_tokens.md) to authenticate with:
+
+- The GitLab API.
+- GitLab repositories.
+- The GitLab registry.
+
+You can limit the scope and expiration date of your personal access tokens. By default,
+they inherit permissions from the user who created them.
+
+## OAuth2 tokens
+
+GitLab can serve as an [OAuth2 provider](../api/oauth2.md) to allow other services to access the GitLab API on a user’s behalf.
+
+You can limit the scope and lifetime of your OAuth2 tokens.
+
+## Impersonation tokens
+
+An [Impersonation token](../api/README.md#impersonation-tokens) is a special type of personal access
+token. It can be created only by an administrator for a specific user. Impersonation tokens can
+help you build applications or scripts that authenticate with the GitLab API, repositories, and the GitLab registry as a specific user.
+
+You can limit the scope and set an expiration date for an impersonation token.
+
+## Project access tokens
+
+[Project access tokens](../user/project/settings/project_access_tokens.md#project-access-tokens)
+are scoped to a project. As with [Personal access tokens](#personal-access-tokens), you can use them to authenticate with:
+
+- The GitLab API.
+- GitLab repositories.
+- The GitLab registry.
+
+You can limit the scope and expiration date of project access tokens. When you
+create a project access token, GitLab creates a [project bot user](../user/project/settings/project_access_tokens.md#project-bot-users). Project
+bot users are service accounts and do not count as licensed seats.
+
+## 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.
+
+Deploy tokens can be managed by project maintainers and owners.
+
+## Deploy keys
+
+[Deploy keys](../user/project/deploy_keys/index.md) allow read-only or read-write access to your repositories by importing an SSH public key into your GitLab instance. Deploy keys cannot be used with the GitLab API or the registry.
+
+This is useful, for example, for cloning repositories to your Continuous Integration (CI) server. By using deploy keys, you don’t have to set up a fake user account.
+
+Project maintainers and owners can add or enable a deploy key for a project repository
+
+## Runner registration tokens
+
+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 admins can obtain them through the GitLab user interface. The registration token is limited to runner registration and has no further scope.
+
+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.
+
+## Runner authentication tokens (also called runner tokens)
+
+After registration, 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.
+
+After authentication with GitLab, the runner receives a [job token](../user/project/new_ci_build_permissions_model.md#job-token), which it uses to execute the job.
+
+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.
+
+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).
+
+## CI/CD job tokens
+
+The [CI/CD](../api/README.md#gitlab-ci-job-token) job token
+is a short lived token only valid for the duration of a job. It gives a CI/CD job
+access to a limited amount of [API endpoints](../api/README.md#gitlab-ci-job-token).
+API authentication uses the job token, by using the authorization of the user
+triggering the job.
+
+The job token is secured by its short life-time and limited scope. It could possibly be leaked if multiple jobs run on the same machine ([like with the shell runner](https://docs.gitlab.com/runner/security/#usage-of-shell-executor)). On Docker Machine runners, configuring [`MaxBuilds=1`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersmachine-section) is recommended to make sure runner machines only ever run one build and are destroyed afterwards. This may impact performance, as provisioning machines takes some time.
+
+## Available scopes
+
+This table shows available scopes per token. Scopes can be limited further on token creation.
+
+|                             | API access | Registry access | Repository access |
+|-----------------------------|------------|-----------------|-------------------|
+| Personal access token       | ✅          | ✅               | ✅                 |
+| OAuth2 token                | ✅          | 🚫               | ✅                 |
+| Impersonation token         | ✅          | ✅               | ✅                 |
+| Project access token        | ✅(1)       | ✅(1)            | ✅(1)              |
+| Deploy token                | 🚫          | ✅               | ✅                 |
+| Deploy key                  | 🚫          | 🚫               | ✅                 |
+| Runner registration token   | 🚫          | 🚫               | ✴️(2)                 |
+| Runner authentication token | 🚫          | 🚫               | ✴️(2)                 |
+| Job token                   | ✴️(3)       | 🚫               | ✅                 |
+
+1. Limited to the one project.
+1. Runner registration and authentication token don't provide direct access to repositories, but can be used to register and authenticate a new runner that may execute jobs which do have access to the repository
+1. Limited to certain [endpoints](../api/README.md#gitlab-ci-job-token).
diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md
index 7a9ed9d435d..1abd4502eb5 100644
--- a/doc/security/two_factor_authentication.md
+++ b/doc/security/two_factor_authentication.md
@@ -61,7 +61,7 @@ The following are important notes about 2FA:
   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#share-with-group-lock)
+  [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.
@@ -129,8 +129,15 @@ verification can be done via a GitLab Shell command:
 ssh git@<hostname> 2fa_verify
 ```
 
-Once the OTP is verified, Git over SSH operations can be used for 15 minutes
-with the associated SSH key.
+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