Merge branch 'docs/52681-add-documentation-about-how-web-terminals-are-secured' into 'master'

Add docs on how web terminals are secured

Closes #52681

See merge request gitlab-org/gitlab-ce!24099

2 files changed, 17 insertions, 1 deletions

diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md
index fa58d0ef15f..a04458f2019 100644
--- a/doc/administration/integration/terminal.md
+++ b/doc/administration/integration/terminal.md
@@ -28,6 +28,19 @@ In brief:
   user no longer has permission to access the terminal, or if the connection
   details have changed.
 
+## Security
+
+GitLab and [GitLab Runner](https://docs.gitlab.com/runner/) take some
+precautions to keep interactive web terminal data encrypted between them, and
+everything protected with authorization guards. This is described in more
+detail below.
+
+- Interactive web terminals are completely disabled unless [`[session_server]`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) is configured.
+- Every time the runner starts, it will generate an `x509` certificate that will be used for a `wss` (Web Socket Secure) connection.
+- For every created job, a random URL is generated which is discarded at the end of the job. This URL is used to establish a web socket connection. The URL for the session is in the format `(IP|HOST):PORT/session/$SOME_HASH`, where the `IP/HOST` and `PORT` are the configured [`listen_address`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section).
+- Every session URL that is created has an authorization header that needs to be sent, to establish a `wss` connection.
+- The session URL is not exposed to the users in any way. GitLab holds all the state internally and proxies accordingly.
+
 ##  Enabling and disabling terminal support
 
 As web terminals use WebSockets, every HTTP/HTTPS reverse proxy in front of
diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md
index d299e28d2e6..0cf9daed22f 100644
--- a/doc/ci/interactive_web_terminal/index.md
+++ b/doc/ci/interactive_web_terminal/index.md
@@ -3,7 +3,10 @@
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/50144) in GitLab 11.3.
 
 Interactive web terminals give the user access to a terminal in GitLab for
-running one-off commands for their CI pipeline.
+running one-off commands for their CI pipeline. Since this is giving the user
+shell access to the environment where [GitLab Runner](https://docs.gitlab.com/runner/) 
+is deployed, some [security precautions](../../administration/integration/terminal.md#security) were
+taken to protect the users.
 
 NOTE: **Note:**
 GitLab.com does not support interactive web terminal at the moment – neither