From c80c3c7e2d5ac1e81095741db78d2b89c2ee95bc Mon Sep 17 00:00:00 2001 From: Zac Bergquist Date: Wed, 22 Jan 2025 11:48:04 -0700 Subject: [PATCH] docs: update moderated sessions guide (#51218) Moderated sessions are a bit confusing because we combined an existing OSS feature (joining sessions), with an Enterprise-only feature (requiring session join policies). I've expanded the scope of the moderated sessions guide to make it a "joining sessions" guide instead, and added some extra details around RBAC for active sessions. Updates #51116 --- CHANGELOG.md | 4 +- docs/config.json | 5 + ...ated-sessions.mdx => joining-sessions.mdx} | 373 ++++++++---------- .../access-controls/guides/webauthn.mdx | 58 +-- .../admin-guides/access-controls/sso/sso.mdx | 33 +- docs/pages/connect-your-client/tsh.mdx | 2 +- docs/pages/connect-your-client/web-ui.mdx | 25 +- .../server-access/troubleshooting-server.mdx | 46 +-- docs/pages/includes/access-control-guides.mdx | 2 +- docs/pages/includes/edition-comparison.mdx | 3 +- docs/pages/includes/role-spec.mdx | 1 - .../pages/reference/access-controls/roles.mdx | 2 +- 12 files changed, 263 insertions(+), 291 deletions(-) rename docs/pages/admin-guides/access-controls/guides/{moderated-sessions.mdx => joining-sessions.mdx} (56%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ee26633013d5..3cccd4af52dc0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1960,7 +1960,7 @@ sessions remains deny-by-default but now only `join_sessions` statements are checked for session join RBAC. See the [Moderated Sessions -guide](docs/pages/admin-guides/access-controls/guides/moderated-sessions.mdx) for more +guide](docs/pages/admin-guides/access-controls/guides/joining-sessions.mdx) for more details. #### GitHub connectors @@ -2419,7 +2419,7 @@ With Moderated Sessions, Teleport administrators can define policies that allow users to invite other users to participate in SSH or Kubernetes sessions as observers, moderators or peers. -[Moderated Sessions guide](docs/pages/admin-guides/access-controls/guides/moderated-sessions.mdx) +[Moderated Sessions guide](docs/pages/admin-guides/access-controls/guides/joining-sessions.mdx) ### Breaking Changes diff --git a/docs/config.json b/docs/config.json index 9485a6085f5df..f8ff91ae673e6 100644 --- a/docs/config.json +++ b/docs/config.json @@ -214,6 +214,11 @@ } }, "redirects": [ + { + "source": "/admin-guides/access-controls/guides/moderated-sessions/", + "destination": "/admin-guides/access-controls/guides/joining-sessions/", + "permanent": true + }, { "source": "/reference/operator-resources/resources.teleport.dev_accesslists/", "destination": "/reference/operator-resources/resources-teleport-dev-accesslists/", diff --git a/docs/pages/admin-guides/access-controls/guides/moderated-sessions.mdx b/docs/pages/admin-guides/access-controls/guides/joining-sessions.mdx similarity index 56% rename from docs/pages/admin-guides/access-controls/guides/moderated-sessions.mdx rename to docs/pages/admin-guides/access-controls/guides/joining-sessions.mdx index 29c2d4513275e..4a792fc6c9e67 100644 --- a/docs/pages/admin-guides/access-controls/guides/moderated-sessions.mdx +++ b/docs/pages/admin-guides/access-controls/guides/joining-sessions.mdx @@ -1,6 +1,6 @@ --- -title: Moderated Sessions -description: Describes the purpose of moderated sessions and how to configure roles to support moderated sessions in a Teleport cluster. +title: Joining Sessions +description: Describes shared sessions and how to configure roles to support joining sessions in a Teleport cluster. keywords: - SSH - Kubernetes @@ -8,45 +8,144 @@ keywords: - audit --- -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: +Teleport allows multiple users to join the same SSH or `kubectl exec` session. +Session joining can be performed via the web UI's Active Sessions page, or by +using the `tsh join` command. -- Observe another user's session in real time. -- Participate interactively in another user's session. -- Terminate another user's session at will. +## Participant modes + +When joining a session, users can be in one of three participant modes: + +- **Observer**: Can only view the session. +- **Peer**: Can view the session and interact with it as if they were the session owner. +- **Moderator**: (Enterprise only) Can view the session and terminate it. + +Users can join SSH sessions from the command line or from the Teleport web UI, +but Kubernetes sessions can only be joined from the command line. + +The web UI forces users to select a join mode prior to joining. 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`. + +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 by pressing `t`. + +## Access controls + +You can use the `join_sessions` field of a role to specify the sessions users +can join and under what conditions they can join a session. For example, the +following role allows users to join both SSH and Kubernetes sessions started by +users with the `prod-access` role and to join the session as a moderator or an +observer: + +```yaml +kind: role +metadata: + name: allow-session-join +version: v7 +spec: + allow: + join_sessions: + - name: Join prod sessions + roles : ['prod-access'] + kinds: ['k8s', 'ssh'] + modes: ['moderator', 'observer'] +``` + +Users who are assigned a role with a `join_sessions` allow policy are +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. + +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`.| + +If you want to allow users to list active sessions without giving them +permission to join these sessions, you can grant them `list` permissions on the +`session_tracker` resource. + +```yaml +kind: role +metadata: + name: list-active-sessions +version: v7 +spec: + allow: + rules: + - resources: [ session_tracker ] + verbs: [ list ] +``` + +Teleport also supports explicit deny rules on the `ssh_session` resource for compatibility +with legacy Teleport roles, but we do not encourage the use of the `ssh_session` resource +in new roles. + +## Moderated sessions + +In Teleport Enterprise, you can configure roles to require that sessions are joined +by 1 or more additional participants before they are allowed to start. Sessions that +require additional participants are called moderated sessions. The most common use cases for moderated sessions involve the following scenarios: - You have strict security or compliance requirements and need to have people watching over user-initiated sessions on a set of servers. -- 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. -Note that you can share terminal sessions using any Teleport edition. However, -you must have Teleport Enterprise if you want to require active sessions to be -observed or moderated. +### Example -## Require and allow policies +In the following example, Jeff's role requires additional participants before it can start. -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. +```code +$ tsh ssh ubuntu@prod.teleport.example.com +Teleport > Creating session with ID: 46e2af03-62d6-4e07-a886-43fe741ca044... +Teleport > Controls + - CTRL-C: Leave the session + - t: Forcefully terminate the session (moderators only) +Teleport > User jeff joined the session. +Teleport > Waiting for required participants... +``` -There are two types of policies you can use to control moderated sessions: +Jeff's session is paused, waiting for the required participants. When Alice, who is +assigned the `auditor` role, joins the waiting session as a moderator, the +session can begin. For example: -- **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. +```code +$ tsh join --mode=moderator 46e2af03-62d6-4e07-a886-43fe741ca044 +Teleport > Creating session with ID: 46e2af03-62d6-4e07-a886-43fe741ca044... +Teleport > Controls + - CTRL-C: Leave the session + - t: Forcefully terminate the session (moderators only) +Teleport > User jeff joined the session. +Teleport > Waiting for required participants... +Teleport > User alice joined the session. +Teleport > Connecting to prod.teleport.example.com over SSH -## Configure a require policy +ubuntu@prod.teleport.example.com % +``` + +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) -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: +### Access controls + +Moderated sessions are configured via the `require_session_join` section of a +role. This section defines the conditions that must be 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 +present in the `moderator` mode to start SSH or Kubernetes sessions: ```yaml kind: role @@ -56,22 +155,16 @@ version: v7 spec: allow: require_session_join: - - name: Auditor oversight + - name: Require one moderator filter: 'contains(user.spec.roles, "auditor")' kinds: ['k8s', 'ssh'] modes: ['moderator'] count: 1 - logins: - - ubuntu - - debian - node_labels: - env: prod - kubernetes_labels: - env: prod - kubernetes_groups: - - prod-access - kubernetes_users: - - USER + logins: [ ubuntu, debian ] + node_labels: { env: prod } + kubernetes_labels: { env: prod } + kubernetes_groups: [ prod-access ] + kubernetes_users: [ USER ] kubernetes_resources: - kind: '*' name: '*' @@ -79,17 +172,11 @@ spec: verbs: ['*'] ``` -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 until the policy requirements are fulfilled. - The `require_session_join` rules apply to all of the user's sessions, including those that are accessible via other roles. If you do not want to require moderation for user sessions, we recommend using Access Requests to temporarily assume a role for resources that should require moderation. -### Required fields - The following are required fields for `require_session_join`: |Option|Type|Description| @@ -98,14 +185,33 @@ The following are required fields for `require_session_join`: |`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.| +|`count`|Integer|The minimum number of users that must join the session to satisfy the policy.| + +The following fields are optional for `require_session_join`: + +|Option|Type|Description| +|---|---|---| +|`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 participant 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. -#### Filter expressions +### 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. +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`: @@ -124,33 +230,6 @@ Filter expressions support the following functions and operators: - `[expr] && [expr]`: Performs a logical AND on two Boolean expressions. - `[expr] || [expr]`: Performs a logical OR on two Boolean expressions. -#### Matching user count - -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. - -### Optional fields - -The following field is optional for `require_session_join`: - -|Option|Type|Description| -|---|---|---| -|`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 @@ -169,130 +248,23 @@ you must include the `require_session_join` policy in the mapped role defined on For more information about configuring trust relationships and role mapping between root and leaf clusters, see [Configure Trusted Clusters](../../management/admin/trustedclusters.mdx). -## 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 -metadata: - name: auditor -version: v7 -spec: - allow: - join_sessions: - - name: Join prod sessions - roles : ['prod-access'] - kinds: ['k8s', 'ssh'] - modes: ['moderator', 'observer'] -``` - -Users who are assigned a role with a `join_sessions` allow policy are -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. - -### Required fields - -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`.| - -### 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 -Teleport > Creating session with ID: 46e2af03-62d6-4e07-a886-43fe741ca044... -Teleport > Controls - - CTRL-C: Leave the session - - t: Forcefully terminate the session (moderators only) -Teleport > User jeff joined the session. -Teleport > Waiting for required participants... -``` - -Jeff's session is paused, waiting for the required observers. -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 -Teleport > Creating session with ID: 46e2af03-62d6-4e07-a886-43fe741ca044... -Teleport > Controls - - CTRL-C: Leave the session - - t: Forcefully terminate the session (moderators only) -Teleport > User jeff joined the session. -Teleport > Waiting for required participants... -Teleport > User alice joined the session. -Teleport > Connecting to prod.teleport.example.com over SSH - -ubuntu@prod.teleport.example.com % -``` - -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) - -### 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. -- `peer`: Allows you to collaborate in the session. You can view output and send input. - -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`. - -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`. - ### Multifactor authentication -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. - -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 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. - -## Session kinds - -Require and allow policies have to specify which sessions they apply to. Valid -options are `ssh` and `k8s`. +If per-session MFA is enabled then moderators who want to join a session will +need to satisfy the same MFA checks as if they were starting a session of their +own. -- `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. +Teleport will also enforce additional presence checks for moderated sessions +when per-session MFA is required. Every 30 seconds, Teleport prompts session +moderators verify their presence by re-authenticating with their MFA device +within the next 15 seconds. This behavior continues throughout the session to +ensure that moderators are always present and watching a given session. -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. +If no MFA input is received within 60 seconds, the moderator is disconnected +from the session, which might cause the session to terminate or pause because a +require policy is no longer satisfied. -## Session invites +### Session invites 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 @@ -303,11 +275,12 @@ This information is propagated to the `session_tracker` resource, which can be used to with a third party, for example, to enable notifications over some external communication system. -## File transfers +### File transfers -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. +SFTP 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 and +must be approved before the file transfer can begin. 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. @@ -322,6 +295,6 @@ all session participants are notified. After enough approvals have been given to satisfy the policy used to start the session, the file transfer automatically begins. -## Related documentation +## See also - [Moderated Sessions](https://github.com/gravitational/teleport/blob/master/rfd/0043-kubeaccess-multiparty.md) diff --git a/docs/pages/admin-guides/access-controls/guides/webauthn.mdx b/docs/pages/admin-guides/access-controls/guides/webauthn.mdx index 425152bc0293a..8d21076257e2f 100644 --- a/docs/pages/admin-guides/access-controls/guides/webauthn.mdx +++ b/docs/pages/admin-guides/access-controls/guides/webauthn.mdx @@ -6,14 +6,14 @@ videoBanner: vQgKkD4ZRDU This guide aims to help you fortify your identity infrastructure and mitigate the risks associated with IdP weaknesses. -An IdP compromise occurs when an attacker gains unauthorized access to your identity management -system, potentially allowing them to impersonate legitimate users, escalate privileges, or access -sensitive information. This can happen through various means, such as exploiting software vulnerabilities, +An IdP compromise occurs when an attacker gains unauthorized access to your identity management +system, potentially allowing them to impersonate legitimate users, escalate privileges, or access +sensitive information. This can happen through various means, such as exploiting software vulnerabilities, stealing credentials, or social engineering attacks. -While many organizations have implemented basic security measures like single sign-on (SSO) and multi-factor authentication (MFA), -these alone may not be sufficient to protect against sophisticated attacks targeting your IdP. -Attackers are constantly evolving their techniques, and traditional security measures may have limitations +While many organizations have implemented basic security measures like single sign-on (SSO) and multi-factor authentication (MFA), +these alone may not be sufficient to protect against sophisticated attacks targeting your IdP. +Attackers are constantly evolving their techniques, and traditional security measures may have limitations or vulnerabilities that can be exploited. ![IdP threat vector tree](../../../../img/access-controls/idp-graph.png) @@ -21,15 +21,15 @@ or vulnerabilities that can be exploited. To enhance your defense against IdP compromises, we recommend implementing the following comprehensive security measures. ## Set up cluster-wide WebAuthn -Implement strong, phishing-resistant authentication across -your entire infrastructure using WebAuthn standards. WebAuthn, a W3C standard and part of FIDO2, -enables public-key cryptography for web authentication. Teleport supports WebAuthn as a multi-factor -for logging into Teleport (via tsh login or Web UI) and accessing SSH nodes or Kubernetes clusters. +Implement strong, phishing-resistant authentication across +your entire infrastructure using WebAuthn standards. WebAuthn, a W3C standard and part of FIDO2, +enables public-key cryptography for web authentication. Teleport supports WebAuthn as a multi-factor +for logging into Teleport (via tsh login or Web UI) and accessing SSH nodes or Kubernetes clusters. It's compatible with hardware keys (e.g., YubiKeys, SoloKeys) and biometric authenticators like Touch ID and Windows Hello. ### Prerequisites -- A running Teleport cluster or Teleport Cloud, version 16 or later. If you want to get started with Teleport, +- A running Teleport cluster or Teleport Cloud, version 16 or later. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial. - The `tctl` admin tool and `tsh` client tool. @@ -159,8 +159,8 @@ $ tsh login --proxy=example.teleport.sh ## Configure per-session MFA -Ensure that multi-factor authentication is required for each session, not just at initial login, -to maintain continuous security. Teleport's per-session MFA enhances security by protecting +Ensure that multi-factor authentication is required for each session, not just at initial login, +to maintain continuous security. Teleport's per-session MFA enhances security by protecting against compromised on-disk certificates. It requires additional MFA checks when initiating new SSH, Kubernetes, database, or desktop sessions. Teleport supports requiring additional multi-factor authentication checks @@ -222,19 +222,19 @@ spec: ``` ## Implement cluster-wide Device Trust -Develop a system to verify and manage trusted devices across your organization, reducing the risk -of unauthorized access from unknown or compromised devices. Device Trust adds an extra layer of security by requiring the use of trusted devices -for accessing protected resources, complementing user identity and role enforcement. This can be -configured cluster-wide or via RBAC. Supported resources include apps (role-based only), SSH nodes, +Develop a system to verify and manage trusted devices across your organization, reducing the risk +of unauthorized access from unknown or compromised devices. Device Trust adds an extra layer of security by requiring the use of trusted devices +for accessing protected resources, complementing user identity and role enforcement. This can be +configured cluster-wide or via RBAC. Supported resources include apps (role-based only), SSH nodes, databases, Kubernetes clusters, and first MFA device enrollment. The latter helps prevent auto-provisioning of new users through compromised IdPs. - We do not currently support Machine ID and Device Trust. Requiring Device Trust - cluster-wide or for roles impersonated by Machine ID will prevent credentials + We do not currently support Machine ID and Device Trust. Requiring Device Trust + cluster-wide or for roles impersonated by Machine ID will prevent credentials produced by Machine ID from being used to connect to resources. - As a work-around, configure Device Trust enforcement on a role-by-role basis and + As a work-around, configure Device Trust enforcement on a role-by-role basis and ensure that it is not required for roles that you will impersonate using Machine ID. @@ -247,7 +247,7 @@ responsible for managing devices, adding new devices to the inventory and removing devices that are no longer in use. - Users with the preset `editor` or `device-admin` role + Users with the preset `editor` or `device-admin` role can register and enroll their device in a single step with the following command: ```code $ tsh device enroll --current-device @@ -403,12 +403,12 @@ successfully enrolled and authenticated. ## Require MFA for administrative actions -Add an extra layer of security for sensitive administrative operations by requiring multi-factor authentication -for these high-privilege actions. Teleport enforces additional MFA verification for administrative -actions across all clients (tctl, tsh, Web UI, and Connect). This feature adds an extra security +Add an extra layer of security for sensitive administrative operations by requiring multi-factor authentication +for these high-privilege actions. Teleport enforces additional MFA verification for administrative +actions across all clients (tctl, tsh, Web UI, and Connect). This feature adds an extra security layer by re-verifying user identity immediately before any admin action, mitigating risks from compromised admin accounts. -By adopting these advanced security measures, you can create a robust defense against IdP compromises and significantly reduce your organization's attack surface. +By adopting these advanced security measures, you can create a robust defense against IdP compromises and significantly reduce your organization's attack surface. In the following sections, we'll dive deeper into each of these recommendations, providing step-by-step guidance on implementation and best practices. @@ -416,10 +416,10 @@ In the following sections, we'll dive deeper into each of these recommendations, with `tctl auth sign` will no longer be suitable for automation due to the additional MFA checks. - We recommend using Machine ID to issue certificates for automated workflows, + We recommend using Machine ID to issue certificates for automated workflows, which uses role impersonation that is not subject to MFA checks. - Certificates produced with `tctl auth sign` directly on an Auth Service instance using the super-admin + Certificates produced with `tctl auth sign` directly on an Auth Service instance using the super-admin role are not subject to MFA checks to support legacy self-hosted setups. @@ -475,7 +475,7 @@ Update the `cluster_auth_preference` definition to include the following content ``` ### Step 2/2. Save and exit the file - + The command `tctl` will update the remote definition: ```text @@ -487,5 +487,5 @@ For additional cluster hardening measures, see: - [Passwordless Authentication](./passwordless.mdx): Provides passwordless and usernameless authentication. - [Locking](./locking.mdx): Lock access to active user sessions or hosts. -- [Moderated Sessions](./moderated-sessions.mdx): Require session auditors and allow fine-grained live session access. +- [Moderated Sessions](./joining-sessions.mdx): Require session auditors and allow fine-grained live session access. - [Hardware Key Support](./hardware-key-support.mdx): Enforce the use of hardware-based private keys. diff --git a/docs/pages/admin-guides/access-controls/sso/sso.mdx b/docs/pages/admin-guides/access-controls/sso/sso.mdx index a6ea082f91061..c19de30c823d6 100644 --- a/docs/pages/admin-guides/access-controls/sso/sso.mdx +++ b/docs/pages/admin-guides/access-controls/sso/sso.mdx @@ -37,7 +37,7 @@ After a user completes an SSO authentication flow, Teleport creates a temporary When a user signs in to Teleport with `tsh login`, they can configure the TTL of the `user` Teleport creates. Teleport enforces a limit of 30 hours (the default is 12 hours). - + In the Teleport audit log, you will see an event of type `user.create` with information about the temporary user. @@ -145,7 +145,7 @@ $ ssh-keygen -L -f ~/.tsh/keys/${TELEPORT_CLUSTER}/${SSO_USER}-ssh/${TELEPORT_CL Since Teleport creates temporary users and issues short-lived certificates when a user authenticates via SSO, it is straightforward to integrate Teleport with multiple SSO providers. Besides the temporary `user` resource, no persistent -backend data in Teleport is tied to a user's account with the SSO provider. +backend data in Teleport is tied to a user's account with the SSO provider. This also means that if one SSO provider becomes unavailable, the end user only needs to choose another SSO provider when signing in to Teleport. While the @@ -187,7 +187,7 @@ The callback address can be changed if calling back to a remote machine instead of the local machine is required: ```code -# --bind-addr sets the host and port tsh will listen on, and --callback changes +# --bind-addr sets the host and port tsh will listen on, and --callback changes # what link is displayed to the user $ tsh login --proxy=proxy.example.com --auth=github --bind-addr=localhost:1234 --callback https://remote.machine:1234 ``` @@ -294,7 +294,7 @@ GitHub as an SSO option. (!docs/pages/includes/sso/saml-slo.mdx!) You may use `entity_descriptor_url` in lieu of `entity_descriptor` to fetch -the entity descriptor from your IDP. +the entity descriptor from your IDP. We recommend "pinning" the entity descriptor by including the XML rather than fetching from a URL. @@ -307,7 +307,7 @@ fetching from a URL. ``` You may use `entity_descriptor_url`, in lieu of `entity_descriptor`, to fetch -the entity descriptor from your IDP. +the entity descriptor from your IDP. We recommend "pinning" the entity descriptor by including the XML rather than fetching from a URL. @@ -334,7 +334,7 @@ fetching from a URL. ``` You may use `entity_descriptor_url`, in lieu of `entity_descriptor`, to fetch -the entity descriptor from your IDP. +the entity descriptor from your IDP. We recommend "pinning" the entity descriptor by including the XML rather than fetching from a URL. @@ -351,7 +351,7 @@ fetching from a URL. (!docs/pages/includes/sso/saml-slo.mdx!) You may use `entity_descriptor_url`, in lieu of `entity_descriptor`, to fetch -the entity descriptor from your IDP. +the entity descriptor from your IDP. We recommend "pinning" the entity descriptor by including the XML rather than fetching from a URL. @@ -366,7 +366,7 @@ fetching from a URL. -Create the connector: +Create the connector: ```code $ tctl create -f connector.yaml @@ -413,13 +413,13 @@ At this time, the `spec.provider` field should not be set for any other identity ## Configuring SSO for MFA checks -Teleport administrators can configure Teleport to delegate MFA checks to an +Teleport administrators can configure Teleport to delegate MFA checks to an SSO provider as an alternative to registering MFA devices directly with the Teleport cluster. This allows Teleport users to use MFA devices and custom flows configured in the SSO provider to carry out privileged actions in Teleport, such as: - [Per-session MFA](../guides/per-session-mfa.mdx) -- [Moderated sessions](../guides/moderated-sessions.mdx) +- [Moderated sessions](../guides/joining-sessions.mdx) - [Admin actions](../guides/mfa-for-admin-actions.mdx) Administrators may want to consider enabling this feature in order to: @@ -434,8 +434,8 @@ Administrators may want to consider enabling this feature in order to: ### Configure the IDP App / Client -There is no standardized MFA flow unlike there is with SAML/OIDC -login, so each IDP may offer zero, one, or more ways to offer MFA checks. +There is no standardized MFA flow unlike there is with SAML/OIDC +login, so each IDP may offer zero, one, or more ways to offer MFA checks. Generally, these offerings will fall under one of the following cases: @@ -448,7 +448,7 @@ which prompts for MFA for an active OIDC session. 2. Use the same IDP app for MFA: Some IDPs provide a way to fork to different flows using the same IDP app. -For example, with Okta (OIDC), you can provide `acr_values: ["phr"]` to +For example, with Okta (OIDC), you can provide `acr_values: ["phr"]` to [enforce phishing resistant authentication](https://developer.okta.com/docs/guides/step-up-authentication/main/#predefined-parameter-values). For a simpler approach, you could use the same IDP app for both login and MFA @@ -483,7 +483,7 @@ and add MFA settings. ``` You may use `entity_descriptor_url` in lieu of `entity_descriptor` to fetch -the entity descriptor from your IDP. +the entity descriptor from your IDP. We recommend "pinning" the entity descriptor by including the XML rather than fetching from a URL. @@ -491,7 +491,7 @@ fetching from a URL. -Update the connector: +Update the connector: ```code $ tctl create -f connector.yaml @@ -525,7 +525,7 @@ spec: Along with sending groups, an SSO provider will also provide a user's email address. In many organizations, the username that a person uses to log in to a system is the -same as the first part of their email address, the "local" part. +same as the first part of their email address, the "local" part. For example, `dave.smith@example.com` might log in with the username `dave.smith`. Teleport provides an easy way to extract the first part of an email address so @@ -673,4 +673,3 @@ which Teleport replaces with values from the single sign-on provider that the user used to authenticate with Teleport. For full details on how variable expansion works in Teleport roles, see the [Teleport Access Controls Reference](../../../reference/access-controls/roles.mdx). - diff --git a/docs/pages/connect-your-client/tsh.mdx b/docs/pages/connect-your-client/tsh.mdx index fe3eb874ceb56..5ec8ba17096fd 100644 --- a/docs/pages/connect-your-client/tsh.mdx +++ b/docs/pages/connect-your-client/tsh.mdx @@ -683,7 +683,7 @@ $ tsh join title="Lacking permission?" > Joining sessions requires special permissions that need to be set up by your cluster administrator. - Refer them to the [Moderated Sessions guide](../admin-guides/access-controls/guides/moderated-sessions.mdx) for more information on configuring join permissions. + Refer them to the [Moderated Sessions guide](../admin-guides/access-controls/guides/joining-sessions.mdx) for more information on configuring join permissions. diff --git a/docs/pages/connect-your-client/web-ui.mdx b/docs/pages/connect-your-client/web-ui.mdx index 9bce88e3eac52..f122d81205f64 100644 --- a/docs/pages/connect-your-client/web-ui.mdx +++ b/docs/pages/connect-your-client/web-ui.mdx @@ -2,8 +2,8 @@ title: Using the Web UI description: Using the Teleport Web UI --- -The Teleport Web UI is a web-based visual interface from which you can access resources, -view active sessions and recordings, create and review Access Requests, +The Teleport Web UI is a web-based visual interface from which you can access resources, +view active sessions and recordings, create and review Access Requests, manage users and roles, and more. This page serves a reference on Web UI features and their usage. @@ -12,24 +12,21 @@ This page serves a reference on Web UI features and their usage. The Teleport Web UI allows you to list and join active SSH sessions using a web-based terminal. -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](../reference/access-controls/roles.mdx). +You can view the active SSH sessions that you are allowed to list by clicking **Active Sessions** in the navigation sidebar. -From the active sessions list, click **Join** and select a participant mode to join the session: +From the active sessions list, click **Join** and select a participant mode to join the session: -- **As an Observer** with read-only access to the session. You can view output but cannot control the session in any way nor +- **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. +- **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. Moderated sessions are an enterprise-only feature. ![joining an active session from the Web UI](../../img/webui-active-session.png) -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](../admin-guides/access-controls/guides/moderated-sessions.mdx). +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](../admin-guides/access-controls/guides/joining-sessions.mdx). ## Idle timeout @@ -68,7 +65,7 @@ cluster networking configuration has been updated ## Starting a database session Starting from version `17.1`, users can establish database sessions using the -Teleport Web UI. Currently, it is supported in PostgreSQL databases. +Teleport Web UI. Currently, it is supported in PostgreSQL databases. To start a new session, locate your database in the resources list and click "Connect". diff --git a/docs/pages/enroll-resources/server-access/troubleshooting-server.mdx b/docs/pages/enroll-resources/server-access/troubleshooting-server.mdx index 82197f31f5832..e1754859994bd 100644 --- a/docs/pages/enroll-resources/server-access/troubleshooting-server.mdx +++ b/docs/pages/enroll-resources/server-access/troubleshooting-server.mdx @@ -27,31 +27,31 @@ Process exited with status 255 ### Solution -You should check the permission settings for the `teleport` binary. +You should check the permission settings for the `teleport` binary. To check the file system permissions on the `teleport` binary: 1. Open a terminal shell on the computer where you have installed the `teleport` service. 1. Determine the location and file system permission of the Teleport binary by running the following command: - + ```code ls -al $(which teleport) ``` The command should return output similar to the following: - + ```text -rwxr-xr-x 1 root wheel 531849504 Aug 30 18:32 /usr/local/bin/teleport ``` - - If you don't see the permission that allows other users to read and execute (-rwxr-x**r-x**), + + If you don't see the permission that allows other users to read and execute (-rwxr-x**r-x**), you should update the permissions. For example: ```code sudo chmod go+rx $(which teleport) ``` - + 1. Restart the `teleport` service. ## Missing logins for single sign-on users @@ -66,8 +66,8 @@ provider don't see any of the logins they need to access remote resources. ### Solution -To fix this issue, you should check that the configuration of your auth connectors assigns logins to -your single sign-on users or modify the traits in the Teleport roles assigned to users through their +To fix this issue, you should check that the configuration of your auth connectors assigns logins to +your single sign-on users or modify the traits in the Teleport roles assigned to users through their group membership in the external identity provider. For more information about using traits in roles, see [Role Templates](../../admin-guides/access-controls/guides/role-templates.mdx). @@ -86,17 +86,17 @@ servers that have previously sent a heartbeat signal to the Teleport Proxy Servi one of these servers subsequently went offline: ``` -Node Name Address Labels --------------- -------------- ----------------------- -ip-172-3-1-242 127.0.0.1:3022 hostname=ip-172-3-1-242 -ip-172-3-1-75 ⟵ Tunnel hostname=ip-172-3-1-75 +Node Name Address Labels +-------------- -------------- ----------------------- +ip-172-3-1-242 127.0.0.1:3022 hostname=ip-172-3-1-242 +ip-172-3-1-75 ⟵ Tunnel hostname=ip-172-3-1-75 ip-172-3-2-177 ⟵ Tunnel hostname=ip-172-3-2-177 ``` ### Solution -To investigate whether a server that previously sent a heartbeat has become unresponsive, you can run the -`tsh ls` or `tctl nodes ls` command with the `--format json` command-line option to see additional +To investigate whether a server that previously sent a heartbeat has become unresponsive, you can run the +`tsh ls` or `tctl nodes ls` command with the `--format json` command-line option to see additional information, including an expiration time. For example: ```json @@ -112,16 +112,16 @@ information, including an expiration time. For example: }, ``` -If the server sends a regular heartbeat signal, the `expires` value should remain relatively consistent, -for example, eight to ten minutes from the current time. If the time to expire is less than the typical -expiration time—for example, within the next two or three minutes from the current time—it's likely that +If the server sends a regular heartbeat signal, the `expires` value should remain relatively consistent, +for example, eight to ten minutes from the current time. If the time to expire is less than the typical +expiration time—for example, within the next two or three minutes from the current time—it's likely that the server has stopped sending the heartbeat. ## Unable to join a shared session -Teleport allows multiple users to observe or participate in active sessions. You can define rules and -configure role-based policies to control which users can join other users' sessions from `tsh` and the -Teleport Web UI. If you are unable to join a shared session, you should check your role assignments +Teleport allows multiple users to observe or participate in active sessions. You can define rules and +configure role-based policies to control which users can join other users' sessions from `tsh` and the +Teleport Web UI. If you are unable to join a shared session, you should check your role assignments and ensure you have a role that include the `join_session` permission. For example: @@ -139,14 +139,14 @@ spec: modes: ['moderator', 'observer'] ``` -For more information about moderated sessions and session sharing, see -[Moderated Sessions](../../admin-guides/access-controls/guides/moderated-sessions.mdx). +For more information about moderated sessions and session sharing, see +[Joining Sessions](../../admin-guides/access-controls/guides/joining-sessions.mdx). ## Unable to connect to agentless OpenSSH server as root You should check your sshd configuration in `/etc/ssh/sshd_config` for a setting like `PermitRootLogin no` or `PermitRootLogin forced-commands-only` - either of these -settings will prevent login as root. +settings will prevent login as root. If you wish to log in as root to an OpenSSH server via Teleport, we recommend changing this setting to `PermitRootLogin prohibit-password`. diff --git a/docs/pages/includes/access-control-guides.mdx b/docs/pages/includes/access-control-guides.mdx index 74b9a4d2801a9..81587d59ca502 100644 --- a/docs/pages/includes/access-control-guides.mdx +++ b/docs/pages/includes/access-control-guides.mdx @@ -6,7 +6,7 @@ - [Per-Session MFA](../admin-guides/access-controls/guides/per-session-mfa.mdx): Per-session multi-mactor authentication. - [MFA for Administrative Actions](../admin-guides/access-controls/guides/mfa-for-admin-actions.mdx): Multi-mactor authentication for admin actions. - [Locking](../admin-guides/access-controls/guides/locking.mdx): Lock access to active user sessions or hosts. -- [Moderated Sessions](../admin-guides/access-controls/guides/moderated-sessions.mdx): Require session auditors and allow fine-grained live session access. +- [Joining Sessions](../admin-guides/access-controls/guides/joining-sessions.mdx): Configure access to existing sessions. - [Hardware Key Support](../admin-guides/access-controls/guides/hardware-key-support.mdx): Enforce the use of hardware-based private keys. - [Device Trust](../admin-guides/access-controls/device-trust/guide.mdx): Register and enforce trusted devices. - [Headless WebAuthn](../admin-guides/access-controls/guides/headless.mdx): Login with Webauthn from a remote device. diff --git a/docs/pages/includes/edition-comparison.mdx b/docs/pages/includes/edition-comparison.mdx index d9ff6ec133199..4d5e3d1fd094b 100644 --- a/docs/pages/includes/edition-comparison.mdx +++ b/docs/pages/includes/edition-comparison.mdx @@ -4,7 +4,7 @@ |---|---|---|---| |[Dual Authorization](../admin-guides/access-controls/guides/dual-authz.mdx)|✖|✔|✔| |[Hardware Key Support](../admin-guides/access-controls/guides/hardware-key-support.mdx)|✖|✔|✔| -|[Moderated Sessions](../admin-guides/access-controls/guides/moderated-sessions.mdx)|✖|✔|✔| +|[Moderated Sessions](../admin-guides/access-controls/guides/joining-sessions.mdx)|✖|✔|✔| |[Role-Based Access Control](../admin-guides/access-controls/guides/role-templates.mdx)|✔|✔|✔| |[Single Sign-On](../admin-guides/access-controls/sso/sso.mdx)|GitHub|GitHub, Google Workspace, OIDC, SAML, Teleport|GitHub, Google Workspace, OIDC, SAML, Teleport| @@ -76,4 +76,3 @@ _Available as an add-on to Teleport Enterprise_ ||Community Edition|Enterprise|Cloud| |---|---|---|---| |Support|Community|24x7 support with premium SLAs and account managers|24x7 support with premium SLAs and account managers| - diff --git a/docs/pages/includes/role-spec.mdx b/docs/pages/includes/role-spec.mdx index ac8ff349abd1f..f293eb9681f63 100644 --- a/docs/pages/includes/role-spec.mdx +++ b/docs/pages/includes/role-spec.mdx @@ -501,7 +501,6 @@ spec: # # session - session playback records # session_tracker - an active session - # ssh_session - allows seeing active sessions page # instance - a Teleport instance # event - structured audit logging event # diff --git a/docs/pages/reference/access-controls/roles.mdx b/docs/pages/reference/access-controls/roles.mdx index 5db6ddd8441c8..d2c51e87b3868 100644 --- a/docs/pages/reference/access-controls/roles.mdx +++ b/docs/pages/reference/access-controls/roles.mdx @@ -87,7 +87,7 @@ There are currently five supported role versions: `v3`, `v4`, `v5`, `v6`, and `v `v4` and higher roles are completely backwards compatible with `v3`. The only difference lies in the default values which will be applied to the role if they are not explicitly set. -Additionally, roles with version `v5` or higher are required to use [Moderated Sessions](../../admin-guides/access-controls/guides/moderated-sessions.mdx). +Additionally, roles with version `v5` or higher are required to use [Moderated Sessions](../../admin-guides/access-controls/guides/joining-sessions.mdx). Label | `v3` Default | `v4` and higher Default ------------------ | -------------- | ---------------