Add documentation for moderated sessions (#9425) (#10302)

docs/config.json

@@ -238,7 +238,8 @@
             { "title": "Second Factor - WebAuthn", "slug": "/access-controls/guides/webauthn/" },
             { "title": "Per-session MFA", "slug": "/access-controls/guides/per-session-mfa/" },
             { "title": "Dual Authorization", "slug": "/access-controls/guides/dual-authz/" },
-            { "title": "Impersonation", "slug": "/access-controls/guides/impersonation/" }
+            { "title": "Impersonation", "slug": "/access-controls/guides/impersonation/" },
+            { "title": "Moderated Sessions", "slug": "/access-controls/guides/moderated-sessions/" }
           ]
         },
         { "title": "Reference", "slug": "/access-controls/reference/" },

docs/pages/access-controls/getting-started.mdx

@@ -122,7 +122,7 @@ Save this role as `interns.yaml`:
 
 ```yaml
 kind: role
-version: v4
+version: v5
 metadata:
   name: interns
 spec:

docs/pages/access-controls/guides.mdx

@@ -23,4 +23,7 @@ layout: tocless-doc
   <li>
     [Locking](./guides/locking.mdx). Lock access to active user sessions or hosts.
   </li>
+  <li>
+    [Moderated Sessions](./guides/moderated-sessions.mdx). Require session auditors and allow fine-grained live session access.
+  </li>
 </ul>

docs/pages/access-controls/guides/dual-authz.mdx

@@ -80,7 +80,7 @@ spec:
 version: v2
 ---
 kind: role
-version: v4
+version: v5
 metadata:
   name: access-plugin
 spec:
@@ -162,7 +162,7 @@ Create `dbadmin`, `reviewer` and `devops` roles:
 
 ```yaml
 kind: role
-version: v4
+version: v5
 metadata:
   name: reviewer
 spec:
@@ -171,7 +171,7 @@ spec:
       roles: ['dbadmin']
 ---
 kind: role
-version: v4
+version: v5
 metadata:
   name: devops
 spec:
@@ -183,7 +183,7 @@ spec:
           deny: 1
 ---
 kind: role
-version: v4
+version: v5
 metadata:
   name: dbadmin
 spec:

docs/pages/access-controls/guides/impersonation.mdx

@@ -32,7 +32,7 @@ Save this file as `jenkins.yaml` to create the user and role:
 
 ```yaml
 kind: role
-version: v4
+version: v5
 metadata:
   name: jenkins
 spec:
@@ -77,7 +77,7 @@ Save this role definition as `impersonator.yaml`:
 
 ```yaml
 kind: role
-version: v4
+version: v5
 metadata:
   name: impersonator
 spec:
@@ -179,7 +179,7 @@ allowed the impersonation of any users or roles with the label
 
 ```yaml
 kind: role
-version: v4
+version: v5
 metadata:
   name: security-impersonator
 spec:
@@ -214,7 +214,7 @@ Create a user and a role `security-scanner` using the following template:
 
 ```yaml
 kind: role
-version: v4
+version: v5
 metadata:
   name: security-scanner
   labels:
@@ -256,7 +256,7 @@ as the label on the role and/or user to impersonate:
 
 ```yaml
 kind: role
-version: v4
+version: v5
 metadata:
   name: security-impersonator
 spec:

docs/pages/access-controls/guides/locking.mdx

@@ -105,7 +105,7 @@ Create a role `locksmith`:
 
 ```yaml
 kind: role
-version: v4
+version: v5
 metadata:
   name: locksmith
 spec:
@@ -231,7 +231,7 @@ It is also possible to configure the locking mode for a particular role:
 
 ```yaml
 kind: role
-version: v4
+version: v5
 metadata:
     name: example-role-with-strict-locking
 spec:

docs/pages/access-controls/guides/moderated-sessions.mdx

@@ -0,0 +1,182 @@
+---
+title: Moderated Sessions
+description: Moderated Sessions
+h1: Moderated Sessions
+---
+
+## Introduction
+
+Moderated Sessions allows Teleport administrators to
+define requirements for other users to be present in a Server or Kubernetes Access session. Depending on the requirements, these users can observe the session in real time, participate in the session, and terminate the session at will.
+
+### Use cases
+
+Moderated Sessions are useful in the following scenarios:
+- When you have stringent security requirements and need to have people watching over user-initiated sessions on a set of servers.
+- When you want to share a terminal with someone else to be able to instruct or collaborate.
+
+## Policies
+
+Moderated Sessions makes use of RBAC policies to allow for fine grained control over
+who can join a session and who is required to be present to start one.
+
+The system is based around **require policies** and **allow policies**. 
+
+Require policies define a set of conditions that must be a met for a session to start or run.
+A minimum of one policy from each relevant role the user has must match for the session to start.
+
+Allow policies are used to define what sessions a user can join
+and under what conditions they may join a session.
+
+## Configuring Moderated Sessions
+
+### `require_session_join`
+
+#### Options
+
+The following are required options for `require_session_join`:
+
+|Option|Type|Description|
+|---|---|---|
+|`name`|String|The name of the require policy|
+|`filter`|[Filter](#filters)|An expression that, if it evaluates to true for a given user, enables the user to be present in a Moderated Session|
+|`kinds`|`[]`[Session kind](#session-kinds)|The kind of session that the policy applies to|
+|`modes`|`[]`[Participant mode](#participant-modes)|The participant mode that applies to the user joining the Moderated Session under this policy|
+|`count`|Integer|The number of users that need to match the filter expression to satisfy the policy|
+
+#### Example
+
+The policy below specifies that the `prod-access` role
+must have a minimum of two users with the role `auditor` and the mode `moderator` present in the session
+to start it. The policy applies to SSH and Kubernetes sessions only.
+
+When a user with this require policy starts a session, it will be pending
+until the policy is fulfilled. 
+
+```yaml
+kind: role
+metadata:
+  name: prod-access
+spec:
+  allow:
+    require_session_join:
+      - name: Auditor oversight
+        filter: 'contains(user.roles, "auditor")'
+        kinds: ['k8s', 'ssh']
+        modes: ['moderator']
+        count: 2
+```
+
+### `join_sessions`
+
+#### Options
+
+The following are required options for `join_sessions`:
+
+|Option|Type|Description|
+|---|---|---|
+|`name`|String|The name of the allow policy|
+|`roles`|[]String|A list of names for Teleport roles that this policy applies to. Users with this role are eligible to join a Moderated Session under this policy.|
+|`kinds`|`[]`[Session kind](#session-kinds)|The kind of session that the policy applies to|
+|`modes`|`[]`[Participant mode](#participant-modes)|The participant mode that applies to the user joining the Moderated Session under this policy|
+
+#### Example
+
+The following allow policy attaches to the role `auditor` and allows one to join
+SSH and Kubernetes sessions started by a user with the role `prod-access` as a moderator or observer.
+
+```yaml
+kind: role
+metadata:
+  name: auditor
+spec:
+  allow:
+    join_sessions:
+      - name: Auditor oversight
+        roles : ['prod-access']
+        kinds: ['k8s', 'ssh']
+        modes: ['moderator', 'observer']
+```
+
+### Filters
+
+Filter expressions allow for more detailed control over the scope of an allow policy or require policy.
+
+Require policies can specify which users they consider as valid with a filter expression.
+The filter context has a `user` object defined with the set fields `roles` and `name`.
+
+Here is an example of a filter expression that evaluates to true if the user is Adam or if the user has the trait `cs-observe`:
+
+```
+equals(user.name, "adam") || contains(user.roles, "cs-observe")
+```
+
+A filter expression is a string statement used to define logic based on a set of input variables.
+The filter expressions follow a restricted subset of Go syntax and supports
+the following functions and operators:
+- `contains(set, item)`: Returns true if the item is in the set, otherwise false. The set can be a string or an array.
+- `equals(a, b)`: Returns true if the two values are equal, otherwise returns false.
+- `![expr]`: Negates a boolean expression.
+- `[expr] && [expr]`: Performs a logical AND on two boolean expressions.
+- `[expr] || [expr]`: Performs a logical OR on two boolean expressions.
+
+### Session kinds
+
+Require and allow policies have to specify which sessions they apply to. Valid options are `ssh` and `k8s`.
+
+- `ssh` policies apply to all SSH sessions on a node running the Teleport SSH server.
+- `k8s` policies apply to all Kubernetes sessions on clusters connected to Teleport.
+
+### Participant modes
+A participant joining a session will always have one of three modes:
+
+- `peer`: Can join and collaborate in a session. They can view output and send input.
+- `moderator`: Can join and watch a session. They can view output and forcefully terminate the session at will.
+- `observer`: Can join and watch a session. They cannot control the session in any way.
+
+When joining a session with `tsh join` or `tsh kube join`, a user can specify a mode with the `--mode <mode>` flag
+, where the mode is one of `peer`, `moderator` or `observer`. By default, the mode is `peer` for SSH and
+`moderator` for Kubernetes sessions.
+
+A participant may leave a session with the shortcut `c` while in observer or moderator mode.
+When in moderator mode, a participant may also forcefully terminate the session at any point in time
+with the shortcut `t`.
+
+### Require policy count
+
+Require policies can have a variable amount of users that need to match the filter expression
+in order to satisfy the policy. The `count` field of a require policy is a positive integer
+value that specifies the minimum amount of users this policy requires.
+
+## Backwards compatibility with Server Access
+
+Previously, Server Access did not include controls over which users can join a session.
+To work around this, RBAC rules are ignored for users that only have V4 roles (`version: v4` in the role specification).
+New roles are created as V5. V4 roles are upgraded when they are modified in the UI.
+If a user has any attached V5 roles (`version: v5` in the role specification), the new RBAC access checks will be enforced.
+
+## MFA-based presence
+
+When `per_session_mfa` is set to `true` via [role or cluster settings](../../access-controls/guides/per-session-mfa.mdx), Teleport enforces
+MFA-based presence checks for moderators.
+This requires that all moderators wishing to join have a configured U2F or WebAuthn MFA token.
+
+Every 30 seconds, Teleport will issue a prompt to the user in the terminal, asking them
+to press their MFA token in the next 15 seconds. This will happen continously during the session
+and exists so that moderators are always present and watching a given session.
+
+If no MFA input is received within 60 seconds, the user is kicked
+from the session which may pause it, if RBAC policies are no longer met.
+
+## Session invites
+
+When starting an interactive SSH or Kubernetes session using `tsh ssh` or `tsh kube exec` respectively,
+one may supply a `--reason <reason>` and/or an `--invited <users>` flag where `<reason>`
+is a string and `<users>` is a comma-separated list of usernames.
+
+This information can be picked up by a third party integration and may for example be used to
+enable notifications over some external communication system.
+
+## RFD
+
+- [Moderated Sessions](https://github.com/gravitational/teleport/blob/master/rfd/0043-kubeaccess-multiparty.md)

docs/pages/access-controls/guides/per-session-mfa.mdx

@@ -87,7 +87,7 @@ Olga defines two Teleport roles: `access-dev` and `access-prod`:
 ```yaml
 # access-dev.yaml
 kind: role
-version: v4
+version: v5
 metadata:
   name: access-dev
 spec:
@@ -100,7 +100,7 @@ spec:
 ---
 # access-prod.yaml
 kind: role
-version: v4
+version: v5
 metadata:
   name: access-prod
 spec:

docs/pages/access-controls/guides/role-templates.mdx

@@ -36,7 +36,7 @@ We can create two roles, one for each user in file `roles.yaml`:
 
 ```yaml
 kind: role
-version: v4
+version: v5
 metadata:
   name: alice
 spec:
@@ -49,7 +49,7 @@ spec:
       '*': '*'
 ---
 kind: role
-version: v4
+version: v5
 metadata:
   name: bob
 spec:
@@ -78,7 +78,7 @@ Let's create a role template `devs.yaml`:
 
 ```yaml
 kind: role
-version: v4
+version: v5
 metadata:
   name: devs
 spec:
@@ -173,7 +173,7 @@ to be set by identity provider. Save this role as `sso-users.yaml`:
 
 ```yaml
 kind: role
-version: v4
+version: v5
 metadata:
   name: sso-users
 spec:
@@ -255,7 +255,7 @@ Let's see how these variables are used with role template `interpolation`:
 
 ```yaml
 kind: role
-version: v4
+version: v5
 metadata:
   name: interpolation
 spec:
@@ -288,7 +288,7 @@ behave as the following role:
 
 ```yaml
 kind: role
-version: v4
+version: v5
 metadata:
   name: interpolation
 spec: