docs: update FAQ (#48938)

Re-order some of the questions to move related topics closer together,
and add a new FAQ that explains how roles are embedded in certificates.

docs/pages/core-concepts.mdx

@@ -39,15 +39,15 @@ Read our guides to how [authorization](reference/architecture/authorization.mdx)
 ### Teleport Proxy Service
 
 The **Teleport Proxy Service** allows for secure access to resources in your
-infrastructure from the public internet without the need for a VPN. 
+infrastructure from the public internet without the need for a VPN.
 
 It establishes reverse tunnels to the **Teleport Auth Service** and **Teleport
 Services**, which can run in private networks. This means that, in the Proxy
 Service's minimal configuration, you can expose only port `443` to the internet
 and run the rest of your infrastructure in private networks.
 
 You can also configure clients to bypass Proxy Service instances and connect to
-resources with Teleport-issued certificates directly. 
+resources with Teleport-issued certificates directly.
 
 Read our guide to [how the Teleport Proxy Service
 works](reference/architecture/proxy.mdx).
@@ -73,7 +73,7 @@ Service](./enroll-resources/application-access/introduction.mdx).
 ### Teleport Database Service
 
 Proxies TCP traffic in the native protocols of popular databases, including
-PostgreSQL and MySQL. 
+PostgreSQL and MySQL.
 
 Read more about the [Teleport Database
 Service](./enroll-resources/database-access/database-access.mdx).
@@ -92,7 +92,7 @@ Proxies HTTP traffic to the Kubernetes API server.
 Read more about the [Teleport Kubernetes
 Service](./enroll-resources/kubernetes-access/introduction.mdx)
 
-### Teleport SSH Service 
+### Teleport SSH Service
 
 An SSH server implementation that allows users to execute commands on remote
 machines while taking advantage of Teleport's built-in access controls,
@@ -104,7 +104,7 @@ Read more about the [Teleport SSH Service](./enroll-resources/server-access/intr
 
 Allows machines and services—called bot users—to communicate securely with
 resources in your infrastructure by automatically provisioning and renewing
-credentials. 
+credentials.
 
 Bot users can connect to resources in your infrastructure without relying
 on static credentials (e.g., certificates and private keys) that become more
@@ -131,7 +131,7 @@ on GitHub.
 
 You can find a detailed comparison of the features available in each Teleport
 edition in [Frequently Asked
-Questions](./faq.mdx#how-is-open-source-different-from-enterprise).
+Questions](./faq.mdx#how-is-teleports-community-edition-different-from-enterprise).
 
 ### Teleport Enterprise Cloud
 
@@ -193,29 +193,29 @@ Ultimately, a Teleport user is the subject of a certificate issued by the
 **Teleport Auth Service**. The Auth Service verifies that a client or service
 attempting to connect has a valid Teleport-issued certificate. It then uses the
 subject of the certificate—including its username and Teleport roles—to
-authorize the user.  
+authorize the user.
 
 Read more about [local users](reference/access-controls/authentication.mdx) and how [SSO
 authentication works in Teleport](admin-guides/access-controls/sso/sso.mdx).
 
 ### Authentication connector
 
 An authentication connector is a **configuration resource** that allows users to
-authenticate to Teleport via a Single Sign-On (SSO) solution. 
+authenticate to Teleport via a Single Sign-On (SSO) solution.
 
 See our guide to [Authentication Options](reference/access-controls/authentication.mdx).
 
 ### Trusted clusters
 
-Teleport allows you to configure a **trusted cluster relationship** between a 
-**root cluster** and one or more **leaf clusters** that trust the root cluster 
-certificate authority. The trust relationship between the root and leaf clusters 
-enables users authenticated in the root cluster to access resources 
+Teleport allows you to configure a **trusted cluster relationship** between a
+**root cluster** and one or more **leaf clusters** that trust the root cluster
+certificate authority. The trust relationship between the root and leaf clusters
+enables users authenticated in the root cluster to access resources
 in leaf cluster. The root and leaf cluster operate independently with their own
 users, roles, and resources, but the trust relationship allows users with certain roles
 in the root cluster to be mapped to roles and permissions defined in the leaf cluster.
 
 For more information about how to configure a trust relationship between clusters,
-see [Configure Trusted Clusters](admin-guides/management/admin/trustedclusters.mdx). 
-For an overview of the architecture used in a trusted cluster relationship, see 
+see [Configure Trusted Clusters](admin-guides/management/admin/trustedclusters.mdx).
+For an overview of the architecture used in a trusted cluster relationship, see
 [Trusted Cluster Architecture](reference/architecture/trustedclusters.mdx).

docs/pages/faq.mdx

@@ -11,32 +11,24 @@ Fortune 500 companies. It has been through several security audits from
 nationally recognized technology security companies, so we are comfortable with
 the stability of Teleport from a security perspective.
 
-## Can Teleport be deployed in agentless mode?
-
-Yes. All Teleport services support agentless mode, where the service proxies
-traffic to an upstream infrastructure resource not available on `localhost`.
+## Can I connect to nodes behind a firewall?
 
-With Teleport in agentless mode, you can easily control access to SSH servers,
-Kubernetes clusters, desktops, databases, and internal applications without
-running any additional software on your servers. Agentless mode supports session
-recordings and audit logs for deep understanding into user behavior.
+Yes, Teleport supports reverse SSH tunnels out of the box. To configure
+behind-firewall clusters, see [Configure Trusted Clusters](admin-guides/management/admin/trustedclusters.mdx).
 
-For capabilities such as kernel-level logging and user provisioning, we
-recommend Teleport as a drop in replacement for OpenSSH. Since Teleport replaces
-the OpenSSH agent while preserving OpenSSH's functionality, you get more
-functionality without a net addition of an agent on your system.
+## How is Teleport's Community Edition different from Enterprise?
 
-## Can I use OpenSSH with a Teleport cluster?
+Teleport provides two editions:
 
-Yes, this question comes up often and is related to the previous one. Take a
-look at [Using OpenSSH Guide](enroll-resources/server-access/openssh/openssh-agentless.mdx).
+- Teleport Enterprise
+- Teleport Community Edition
 
-## Can I connect to nodes behind a firewall?
+Here is a detailed breakdown of the differences between Teleport's editions.
 
-Yes, Teleport supports reverse SSH tunnels out of the box. To configure
-behind-firewall clusters, see [Configure Trusted Clusters](admin-guides/management/admin/trustedclusters.mdx).
+(!docs/pages/includes/edition-comparison.mdx!)
 
 ## Should we use Teleport Enterprise or Teleport Community Edition for connecting resources to our Teleport cluster?
+
 (!docs/pages/includes/ent-vs-community-faq.mdx!)
 
 ## Can individual agents create reverse tunnels to the Proxy Service without creating a new cluster?
@@ -54,6 +46,26 @@ Yes, Teleport supports tunnel multiplexing on a single port. Set the
 setting in the `proxy_service` configuration. Teleport will automatically use
 multiplexing with that configuration.
 
+## Can Teleport be deployed in agentless mode?
+
+Yes. All Teleport services support agentless mode, where the service proxies
+traffic to an upstream infrastructure resource not available on `localhost`.
+
+With Teleport in agentless mode, you can easily control access to SSH servers,
+Kubernetes clusters, desktops, databases, and internal applications without
+running any additional software on your servers. Agentless mode supports session
+recordings and audit logs for deep understanding into user behavior.
+
+For capabilities such as kernel-level logging and user provisioning, we
+recommend Teleport as a drop in replacement for OpenSSH. Since Teleport replaces
+the OpenSSH agent while preserving OpenSSH's functionality, you get more
+functionality without a net addition of an agent on your system.
+
+## Can I use OpenSSH with a Teleport cluster?
+
+Yes, this question comes up often and is related to the previous one. Take a
+look at [Using OpenSSH Guide](enroll-resources/server-access/openssh/openssh-agentless.mdx).
+
 ## Can I copy files from one Teleport node to another?
 
 Yes, Teleport supports [Headless WebAuthn authentication](admin-guides/access-controls/guides/headless.mdx),
@@ -65,7 +77,7 @@ are not logged in to Teleport or may not have access to a browser.
 If your host machine is joined to an Active Directory domain, you might find user lookups take a
 lot longer than you expect. The number of Active Directory accounts that must be scanned to
 perform a user lookup can cause tsh to hang waiting to get information about the current user.
-To fix this issue, you can use environment variables to set default account information for your 
+To fix this issue, you can use environment variables to set default account information for your
 Teleport user. If you are experiencing long lookup times on Windows, do the following:
 
 - Either set the `TELEPORT_USER` environment variable or set the `--user` flag to the name of your Teleport user.
@@ -75,18 +87,6 @@ Teleport user. If you are experiencing long lookup times on Windows, do the foll
 You can set these environment variables globally in Windows so that you don't have to set them every
 time you run `tsh`.
 
-## How is Open Source different from Enterprise?
-
-Teleport provides three editions:
-
-- Teleport Enterprise
-- Teleport Enterprise Cloud
-- Teleport Community Edition
-
-Here is a detailed breakdown of the differences between Teleport's editions.
-
-(!docs/pages/includes/edition-comparison.mdx!)
-
 ## Which version of Teleport is supported?
 
 Teleport releases a new major version approximately every 4 months, and provides
@@ -121,6 +121,19 @@ Please refer to our [Networking](./reference/networking.mdx) guide.
 Teleport offers this feature for the Enterprise (Cloud) and Enterprise
 (Self-Hosted) versions of Teleport.
 
+## Why do changes to a user's role set only take effect on the log next login?
+
+A Teleport user's assigned roles are embedded in the client certificate they
+receive upon logging on. This certificate remains valid and can be used until
+its expiry, even if the user's role set has changed.
+
+To get a new certificate with the new role set, the user will need to log out
+and log back in.
+
+Revocation of Teleport access should be done with Teleport's
+[session and identity locks](./admin-guides/access-controls/guides/locking.mdx),
+not by removing roles.
+
 ## Does Teleport support provisioning users via SCIM?
 
 Teleport supports [SCIM](https://scim.cloud/) provisioning for Okta via the
@@ -144,7 +157,10 @@ Service and Auth Service, as well as agents running other Teleport Services.
 
 Teleport requires a minimum of TLS version 1.2.
 
-This means that when applications and clients establish or accept TLS connections with Teleport processes, they must use TLS 1.2 or a higher protocol version. Teleport enforces this requirement in all operations that involve TLS connections.
+This means that when applications and clients establish or accept TLS
+connections with Teleport processes, they must use TLS 1.2 or a higher protocol
+version. Teleport enforces this requirement in all operations that involve TLS
+connections.
 
 ## Can I suppress warnings about available upgrades?