docs: update moderated sessions guide

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

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

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

@@ -6,30 +6,30 @@ 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)
 
 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
 </Admonition>
 
 ## 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.
 
 <Admonition type="warning" title="Machine ID and Device Trust">
 
-  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.
 </Admonition>
 
@@ -247,7 +247,7 @@ responsible for managing devices, adding new devices to the inventory and
 removing devices that are no longer in use.
 
 <Admonition type="tip" title="Self enrollment">
-  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,23 +403,23 @@ 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.
 
 <Notice type="warning">
   When MFA for administrative actions is enabled, user certificates produced
   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.
 </Notice>
 
@@ -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.

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.
 </TabItem>
 </Tabs>
 
-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,15 +483,15 @@ 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.
 
 </TabItem>
 </Tabs>
 
-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, `[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
@@ -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).
-

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
 
@@ -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".