diff --git a/docs/pages/access-controls/guides/moderated-sessions.mdx b/docs/pages/access-controls/guides/moderated-sessions.mdx index 442b1d2ced0a8..c28ebabe62882 100644 --- a/docs/pages/access-controls/guides/moderated-sessions.mdx +++ b/docs/pages/access-controls/guides/moderated-sessions.mdx @@ -1,79 +1,52 @@ --- title: Moderated Sessions -description: Moderated Sessions -h1: Moderated Sessions +description: Describes the purpose of moderated sessions and how to configure roles to support moderated sessions in a Teleport cluster. +keywords: + - SSH + - Kubernetes + - session moderation + - audit --- -## Introduction +Moderated sessions allow you to define requirements for other users to be present +in an active server or Kubernetes session started by another user. Depending on the +requirements you specify, users who are allowed to join other users' sessions can be +granted permission to do the following: -Moderated Sessions allows Teleport administrators to define requirements for -other users to be present in a server or Kubernetes session. Depending on the -requirements, these users can observe the session in real time, participate in -the session, and terminate the session at will. +- Observe another user's session in real time. +- Participate interactively in another user's session. +- Terminate another user's session at will. -In addition, Teleport administrators can [define rules](#join_sessions) that allow users to join each other's -sessions from `tsh` and the Web UI. +The most common use cases for moderated sessions involve the following scenarios: - - - Moderated Sessions requires Teleport Enterprise or Teleport Enterprise Cloud. - - - -### Use cases - -Moderated Sessions are useful in the following scenarios: -- When you have stringent security requirements and need to have people watching +- You have strict security or compliance 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. +- You want to share a terminal with someone else to be able to instruct or collaborate. +- You need the ability to pause or terminate active sessions. -The system is based around **require policies** and **allow policies**. +Note that you can share terminal sessions using any Teleport edition. However, you must +have Teleport Enterprise or Teleport Enterprise Cloud if you want to require active +sessions to be observed or moderated. -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. +## Require and allow policies -Allow policies are used to define what sessions a user can join and under what -conditions they may join a session. +Moderated sessions use roles to provide fine grained control over who can join a session +and who is required to be present to start one. -## Configuring Moderated Sessions +There are two types of policies you can use to control moderated sessions: -### `require_session_join` +- **Require** policies define a set of conditions that must be a met for a session to + start or run. A user assigned a role with a require policy must meet the minimum + requirements of the policy to start the session that the policy applies to. +- **Allow** policies define what sessions users can join and under what conditions + they can join a session. -#### 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| +## Configure a require policy -The following fields are optional for `require_session_join`: - -|Option|Type|Description| -|---|---|---| -|`on_leave`|[On leave](#on-leave)|The action to take when the policy is no longer satisfied| - -#### 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. - -This policy requires that at least one user with the `auditor` role is present -as a moderator for SSH or Kubernetes sessions to start. That is applied for -servers and Kubernetes resources labeled `env: prod`. The session will not start -until the policy is fulfilled. +In Teleport Enterprise editions, you can use `require_session_join` in a role to specify +the conditions that must be a met for a session to start or run. For example, the following +policy specifies that users assigned the `prod-access` role must have a minimum of one user +with the `auditor` role and the `moderator` mode present to start SSH or Kubernetes sessions: ```yaml kind: role @@ -106,33 +79,97 @@ spec: verbs: ['*'] ``` -#### Combining Policies +Because this sample policy requires that at least one user with the `auditor` role to be present +as a moderator to start SSH or Kubernetes sessions, a user assigned this `prod-access` role +won't be able to start any sessions on matching resources until the policy requirements are fulfilled. + +### Required fields + +The following are required fields for `require_session_join`: + +|Option|Type|Description| +|---|---|---| +|`name`|String|The name of the require policy| +|`filter`|Filter|An expression that, if it evaluates to true for a given user, enables the user to be present in a moderated session.| +|`kinds`|List|The kind of session—SSH, Kubernetes, or both—that the policy applies to. The valid options are `ssh` and `k8s`.| +|`modes`|List|The participant mode—`observer`, `moderator`, or `peer`—that the user joining the moderated session must match to satisfy the policy.| +|`count`|Integer|The minimum number of users that must match the filter expression to satisfy the policy.| + +#### Filter expressions + +Filter expressions allow for more detailed control over the scope of a policy. +For example, you can use a filter expression to specify which users are required +to be present in a session. The filter has a `user` object as its context that you +can refine to match the `roles` and `name` fields you specify. + +In the following example, the filter expression evaluates to true if the user's name is +`adam` or if the user has the role `cs-observe`: + +``` +equals(user.name, "adam") || contains(user.spec.roles, "cs-observe") +``` + +Filter expressions support the following functions and operators: -The authorizer applies require policies within a role together with an OR operator and the policies from each role with an AND operator. In practice, this means that for every role with at least one require policy, one of its policies must be met before a session can be started. +- `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. -### `join_sessions` +#### Matching user count -#### Options +You can use the `count` field in a require policy to specify the minimum number +of users matching the filter expression who must be present in a session to satisfy +the policy. -The following are required options for `join_sessions`: +### Optional fields + +The following field is optional for `require_session_join`: |Option|Type|Description| |---|---|---| -|`name`|String|The name of the allow policy| -|`roles`|[]String|A list of names of Teleport roles whose sessions this policy applies to. Active sessions created by users with these roles can be joined 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 session under this policy| +|`on_leave`|String|The action to take when the policy is no longer satisfied.| + +You can use the `on_leave` field in require policies to define what happens +when a moderator leaves a session and causes the policy to no longer be satisfied. +There are two possible values for this field: + +- `terminate` to terminate the session immediately and disconnect all participants. +- `pause` to pause the session and stop any input/output streaming until the policy is satisfied again. + +By default, Teleport treats an empty string in this field the same as `terminate`. + +If all require policies attached to the session owner are set to `pause`, the session +discards all input from session participants and buffers the most recent output but +the session remains open so it can resume. + +### Combining require policies and roles + +In evaluating policies and roles, all of the require policies within a role are evaluated using an +OR operator and the policies from each role are evaluated using an AND operator. In practice, this +means that for every role with at least one require policy, one of its policies must be met before +a user assigned the role can start a session. - -Joining from the UI is available for SSH sessions. Kubernetes sessions can only be joined from the CLI. - +### Requiring moderated sessions in a leaf cluster +If you create a role with the `require_session_join` policy in a root cluster, only sessions started +on resources in the root cluster are required to be moderated for the users assigned that role. +If users assigned the role connect to resources in a leaf node, their sessions won't require moderation, +unless the mapped leaf role also requires moderation. To require moderated sessions in the leaf cluster, +you must include the `require_session_join` policy in the mapped role defined on the leaf cluster. -#### Example Moderator Role +For more information about configuring trust relationships and role mapping between root and leaf +clusters, see [Configure Trusted Clusters](../../management/admin/trustedclusters.mdx). -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. +## Configure an allow policy + +You can use `join_sessions` in a role to specify the sessions users can join and under what conditions +they can join a session. For example, the following policy is attached to the `auditor` role and allows +a user assigned to the auditor role to join SSH and Kubernetes sessions started by a user with the +role `prod-access` and to join the session as a moderator or an observer: ```yaml kind: role @@ -142,7 +179,7 @@ version: v7 spec: allow: join_sessions: - - name: Auditor oversight + - name: Join prod sessions roles : ['prod-access'] kinds: ['k8s', 'ssh'] modes: ['moderator', 'observer'] @@ -153,12 +190,23 @@ implicitly allowed to list the sessions that the policy gives them permission to join. If there's a `deny` rule that prevents listing sessions, the `join_sessions` policy overrides the `deny` rule for the sessions the policy allows the user to join. Outside of this exception for joining -sessions, `deny` statements take precedent. +sessions, `deny` statements take precedent. + +### Required fields -#### Joining sessions example +The following are required fields for `join_sessions`: + +|Option|Type|Description| +|---|---|---| +|`name`|String|The name of the allow policy.| +|`roles`|List|A list of Teleport role names that the allow policy applies to. Active sessions created by users with these roles can be joined under this policy.| +|`kinds`|List|The kind of sessions—SSH, Kubernetes, or both—that the allow policy applies to. The valid options are `ssh` and `k8s`.| +|`modes`|List|The participant mode—`observer`, `moderator`, or `peer`—that the user joining the session can use to join the session. The default mode is `observer`.| -Here is an example of Jeff with role `prod-access` connecting to -a SSH server in the production environment. +### Joining a session from the command line + +In the following example, Jeff is assigned the `prod-access` role and attempts to connect to +a server in the production environment using `tsh ssh`: ```code $ tsh ssh ubuntu@prod.teleport.example.com @@ -171,9 +219,9 @@ Teleport > Waiting for required participants... ``` Jeff's session is paused, waiting for the required observers. - -Now Alice with the `auditor` role joins as a moderator and -the session can begin. +When Alice, who is assigned the `auditor` role, joins the waiting session +as a moderator, the session can begin. +For example: ```code $ tsh join --mode=moderator 46e2af03-62d6-4e07-a886-43fe741ca044 @@ -189,139 +237,85 @@ Teleport > Connecting to prod.teleport.example.com over SSH ubuntu@prod.teleport.example.com % ``` -Here is an example of joining from the UI that is available for server sessions. +Because this session is an SSH session, Alice could also join from the +Teleport Web UI. For example: ![Join Server Session from UI](../../../img/webui-active-session.png) -### 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.spec.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: -- `observer`: Allows read-only access to the session. You can view output but cannot control the session in any way nor send any input. -- `moderator`: Allows you to watch the session. You can view output and forcefully terminate or pause the session at any time, but can't send input. +- `observer`: Allows read-only access to the session. You can view output but + cannot control the session in any way nor send any input. +- `moderator`: Allows you to watch the session. You can view output and forcefully + terminate or pause the session at any time, but can't send input. - `peer`: Allows you to collaborate in the session. You can view output and send input. -When joining a session with `tsh join` or `tsh kube join`, a user can specify a -participant mode with the `--mode ` flag , where the mode is one of `peer`, -`moderator` or `observer`. By default, the mode is `observer`. - -A participant may leave a session with the shortcut `^c` (Control + 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. +If you join a session with `tsh join` or `tsh kube join`, you can specify a +participant mode with the `--mode ` command-line option, where `` is `peer`, +`moderator`, or `observer`. The default participant mode is `observer`. -### On leave +You can leave a session with the shortcut `^c` (Control + c) while in observer or +moderator mode. In moderator mode, you can also forcefully terminate the session +at any point in time with the shortcut `t`. -The `on_leave` string option in require policies is used to define what happens when a moderator leaves a session, causing a policy to no longer be satisfied. +### Multifactor authentication -There are two possible actions to take in this scenario: -- Terminate the session and disconnect all participants, corresponding to the `"terminate"` value. -- Pause the session and stop any input/output streaming until the policy is satisfied again, corresponding to the `"pause"` value. +If `per_session_mfa` is set to `true` in role or cluster settings, Teleport requires +multifactor authentication checks when starting new sessions. This requirement is +also enforced for session moderators. Therefore, moderators who want to join a session +must have configured a device for multifactor authentication. -By default, Teleport treats an empty string in this field as the same as `terminate`. -That is, the session is terminated instantly and all participants are disconnected. +Every 30 seconds, Teleport prompts session moderators to re-authenticate within the +next 15 seconds. This behavior continues throughout the session to ensure that +moderators are always present and watching a given session. -If all require policies attached to the session owner are set to `"pause"`, the session will instead pause -but the session will remain open. This discards all input from session participants and buffers the most recent output until the session can resume. +If no MFA input is received within 60 seconds, the user is disconnected from the +session, which might cause the session to terminate or pause because a require policy +is no longer satisfied. -## Backwards compatibility with Server Access +## Session kinds -Moderated Session RBAC controls were added to the role specification in version 5 -(`version: v5` in the YAML definition). -Previously, the Teleport SSH Service did not include controls over which users can join a -session. -To avoid breaking functionality for users with only roles on v4 or older, RBAC -access checks will only be enforced if the user has at least one v5 role. - -New roles will be created as v5 by default, and older roles can by updated with -`tctl` or from the Web UI by modifying the `version` field. - -## 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. +Require and allow policies have to specify which sessions they apply to. Valid +options are `ssh` and `k8s`. -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 -continuously during the session and exists so that moderators are always present -and watching a given session. +- `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. -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. +Users with the `join_sessions` permission for SSH sessions can join sessions from the +command line or from the Teleport Web UI. Users with the `join_sessions` permission for +Kubernetes sessions can only join session from the command line. ## Session invites -When starting an interactive SSH or Kubernetes session using `tsh ssh` or `tsh -kube exec` respectively, one may supply a `--reason ` and/or an -`--invited ` flag where `` is a string and `` is a -comma-separated list of usernames. +When starting an interactive SSH or Kubernetes session using `tsh ssh` or `tsh kube exec` +respectively, you can supply the `--reason ` or `--invited ` command-line +option to specify `` as a string or `` as a comma-separated list of +user names. -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. +You can use this information to integrate with a third party, for example, to enable +notifications over some external communication system. ## File transfers -File transfers within moderated sessions are available via the Web UI only. When initiating a file transfer, if the -current active session requires moderation, a file transfer request will automatically be sent to all current party members. +File transfers within moderated sessions are only supported when using the Teleport Web UI. +If the current active session requires moderation, file transfer requests are automatically +sent to all current session participants. -Both the session originator and the moderator(s) must be present in the Web UI during the file transfer initiation to receive -the file transfer request notification. Once the file transfer has been requested, all members of the party will be notified -and prompted with an Approve/Deny dialog. +Both the session originator and the moderator(s) must be present in the Teleport Web UI +during the file transfer initiation to receive the file transfer request notification. +After the file transfer has been requested, all session participants and notified +and prompted to approve or deny the file transfer request. ![Approve/Deny Prompt](../../../img/moderated-file-transfer-dialog.png) +If a moderator denies the file transfer request, the request is immediately removed and +all session participants are notified. -If a moderator denies the file transfer request, the request is immediately removed and all party members are notified. - -After enough approvals have been given to satisfy the policy (the same policy to start the session), the file transfer -will automatically begin. +After enough approvals have been given to satisfy the policy used to start the session, +the file transfer automatically begins. - -## RFD +## Related documentation - [Moderated Sessions](https://github.com/gravitational/teleport/blob/master/rfd/0043-kubeaccess-multiparty.md) - diff --git a/docs/pages/connect-your-client/web-ui.mdx b/docs/pages/connect-your-client/web-ui.mdx index 707da5616d14e..ea98ce6975fec 100644 --- a/docs/pages/connect-your-client/web-ui.mdx +++ b/docs/pages/connect-your-client/web-ui.mdx @@ -10,20 +10,24 @@ This page serves a reference on Web UI features and their usage. ## Joining an active session -The Web UI allows you to list and join active SSH sessions via a web-based terminal. +The Teleport Web UI allows you to list and join active SSH sessions using a web-based terminal. -Any active SSH sessions that you are allowed to list will be listed on the "Active Sessions" page, which can be -accessed from the navigation bar on the left side. If you don't see the "Active Sessions" tab, it means that your user's role doesn't grant -you `list` access for the `ssh_session` resource. Please refer to the [Teleport Access Controls Reference](../access-controls/reference.mdx) -and make sure your role has all the necessary permissions. +You can view the active SSH sessions that you are allowed to list by clicking **Active Sessions** in the navigation sidebar. +You can only see active sessions if you are assigned a role with `list` access for the `ssh_session` resource. +For more information about role permissions and access to resources, see [Teleport Access Controls +Reference](../access-controls/reference.mdx). -Upon clicking on the "Join" button to join an active session, you must choose from one of 3 participant modes to join the session in: +From the active sessions list, click **Join** and select a participant mode to join the session: -- `observer`: Allows read-only access to the session. You can view output but cannot control the session in any way nor send any input. -- `moderator`: Allows you to watch the session. You can view output and forcefully terminate or pause the session at any time, but can't send input. -- `peer`: Allows you to collaborate in the session. You can view output and send input. +- **As an Observer** with read-only access to the session. You can view output but cannot control the session in any way nor + send any input. +- **As a Moderator** with permission to watch, pause, or terminate the session. You can view output and forcefully terminate + or pause the session at any time, but can't send input. +- **As a Peer** to collaborate in the session. You can view output and send input. ![joining an active session from the Web UI](../../img/webui-active-session.png) -If the launch button is missing, then you don't have permission to join in any participant mode. Please refer to the [`join_sessions` allow policy reference](../access-controls/guides/moderated-sessions.mdx#join_sessions) to learn how to grant roles access to participant modes. +You must have the `join_sessions` allow policy in a role you've been assigned to join sessions in any participant mode. +For information about how to configure the `join_sessions` allow policy and participant modes for a role, see +[Configure an allow policy](../access-controls/guides/moderated-sessions.mdx#configure-an-allow-policy).