docs: update moderated sessions guide (#51388)

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

@@ -5464,7 +5464,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
@@ -5923,7 +5923,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
 

docs/config.json

@@ -206,5 +206,11 @@
       }
     }
   },
-  "redirects": []
+  "redirects": [
+    {
+      "source": "/admin-guides/access-controls/guides/moderated-sessions/",
+      "destination": "/admin-guides/access-controls/guides/joining-sessions/",
+      "permanent": true
+    }
+  ]
 }

docs/pages/admin-guides/access-controls/guides/webauthn.mdx

@@ -235,6 +235,7 @@ $ tsh login --proxy=mytenant.teleport.sh
   SSO users should configure multi-factor authentication in their SSO provider.
 </Admonition>
 
+
 ## U2F
 
 WebAuthn has replaced U2F in Teleport from previous versions. If you haven't configured U2F
@@ -252,9 +253,6 @@ re-registered.
 For example, consider the U2F configuration below:
 
 ```yaml
-# snippet from /etc/teleport.yaml showing a U2F configuration:
-auth_service:
-  authentication:
     type: local
     second_factor: u2f
     u2f:
@@ -304,13 +302,10 @@ auth_service:
       # rp_id is the public domain of the Teleport Proxy Service.
       # It's similar to the U2F app_id, but without "https://" or port number.
       rp_id: example.com
-      attestation_allowed_cas:
-      - "/path/to/u2f_attestation_ca.pem"
-```
+  ```
 
 ## Next steps
 
 - [Passwordless](./passwordless.mdx)
 - [Set up per-session MFA checks](./per-session-mfa.mdx)
 - [Require MFA for administrative actions](./mfa-for-admin-actions.mdx)
-

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
@@ -262,7 +262,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.
@@ -275,7 +275,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.
@@ -302,7 +302,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.
@@ -319,7 +319,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.
@@ -334,7 +334,7 @@ fetching from a URL.
 </TabItem>
 </Tabs>
 
-Create the connector: 
+Create the connector:
 
 ```code
 $ tctl create -f connector.yaml
@@ -383,7 +383,7 @@ At this time, the `spec.provider` field should not be set for any other identity
 
 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, `[email protected]` might log in with the username `dave.smith`.
 Teleport provides an easy way to extract the first part of an email address so
@@ -530,4 +530,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).
-

docs/pages/connect-your-client/tsh.mdx

@@ -683,7 +683,7 @@ $ tsh join <session_ID>
   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.
 </Admonition>
 
 <Notice type="note" scope={["oss", "enterprise"]}>

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
 

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`.
 

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.

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|
-

docs/pages/includes/role-spec.mdx

@@ -453,7 +453,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
     #

docs/pages/reference/access-controls/roles.mdx

@@ -85,7 +85,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
 ------------------ | -------------- | ---------------