Refactoring of architecture section. (#13651)

Our architecture section was written almost 5 years ago and was completely obsolete. I refactored all of it to be up to date, added Kuberentes and other resource type references, replaced and created new diagrams.
2026-10-31 03:27:49 +08:00 · 2022-06-23 18:39:49 +00:00
parent 8c2ced7e2b
commit 7fc8f4dfd6
59 changed files with 1145 additions and 1126 deletions
@@ -902,28 +902,28 @@
      "title": "Architecture",
      "entries": [
        {
-          "title": "Architecture Overview",
+          "title": "Overview",
          "slug": "/architecture/overview/"
        },
        {
-          "title": "Teleport Users",
-          "slug": "/architecture/users/"
-        },
-        {
-          "title": "Teleport Nodes",
-          "slug": "/architecture/nodes/"
-        },
-        {
-          "title": "Teleport Auth",
+          "title": "Authentication",
          "slug": "/architecture/authentication/"
        },
+        {
+          "title": "Authorization",
+          "slug": "/architecture/authorization/"
+        },
        {
          "title": "Teleport Proxy",
          "slug": "/architecture/proxy/"
        },
        {
          "title": "Trusted Clusters",
-          "slug": "/trustedclusters/"
+          "slug": "/architecture/trustedclusters/"
+        },
+        {
+          "title": "Teleport Nodes",
+          "slug": "/architecture/nodes/"
        },
        {
          "title": "TLS Routing",
@@ -1020,6 +1020,11 @@
    }
  },
  "redirects": [
+    {
+      "source": "/architecture/users/",
+      "destination": "/architecture/authorization/",
+      "permanent": true
+    },
    {
      "source": "/user-manual/",
      "destination": "/server-access/guides/tsh/",
@@ -1321,4 +1326,4 @@
      "permanent": true
    }
  ]
-}
+}
@@ -57,151 +57,9 @@ $ tctl get roles

 (!docs/pages/includes/backup-warning.mdx!)

-A role definition looks like this:
+Here is a full role specification:

-```yaml
-kind: role
-version: v5
-metadata:
-  name: example
-spec:
-  # Options used for user sessions with default values:
-  options:
-    # max_session_ttl defines the TTL (time to live) of SSH certificates
-    # issued to the users with this role.
-    max_session_ttl: 8h
-    # forward_agent controls whether SSH agent forwarding is allowed
-    forward_agent: true
-    # port_forwarding controls whether TCP port forwarding is allowed
-    port_forwarding: true
-    # client_idle_timeout determines if SSH sessions to cluster nodes are forcefully
-    # terminated after no activity from a client (idle client). it overrides the
-    # global cluster setting. examples: "30m", "1h" or "1h30m"
-    client_idle_timeout: never
-    # Determines if the clients will be forcefully disconnected when their
-    # certificates expire in the middle of an active SSH session.
-    # It overrides the global cluster setting.
-    disconnect_expired_cert: no
-    # Optional: max_connections Per-user limit of concurrent sessions within a
-    # cluster.
-    max_connections: 2
-    # Optional: max_sessions total number of session channels that can be established
-    # across a single connection. 10 will match OpenSSH default behavior.
-    max_sessions: 10
-    # permit_x11_forwarding allows users to use X11 forwarding with openssh clients and servers through the proxy
-    permit_x11_forwarding: true
-    # Specify whether or not to record the user's desktop sessions.
-    # Desktop session recording is enabled if one or more of the user's
-    # roles has enabled recording. Defaults to true if unspecified.
-    # Desktop sessions will never be recorded if auth_service.session_recording
-    # is set to 'off' in teleport.yaml or if the cluster's session_recording_config
-    # resource has set 'mode: off'.
-    record_sessions:
-      desktop: true
-    # Specify whether clipboard sharing should be allowed with the
-    # remote desktop (requires a supported browser). Defaults to true
-    # if unspecified. If one or more of the user's roles has disabled
-    # the clipboard, then it will be disabled.
-    desktop_clipboard: true
-    # Specify a list of names and associated values to be included in user SSH keys.
-    # The key type can only be "ssh" and the mode can only be "extension".
-    # The name and value fields can be arbitrary strings and the value field
-    # supports variable interpolation.
-    cert_extensions:
-     - type: ssh
-       mode: extension
-       name: login@github.com
-       value: "{{ external.github_login }}"
-  # The allow section declares a list of resource/verb combinations that are
-  # allowed for the users of this role. By default, nothing is allowed.
-  allow:
-    # The logins array defines the OS/UNIX logins a user is allowed to use.
-    # a few special variables are supported here (see below)
-    logins: [root, '{{internal.logins}}']
-    # Windows logins a user is allowed to use for desktop sessions.
-    windows_desktop_logins: [Administrator, '{{internal.logins}}']
-    # If the Kubernetes integration is enabled, this setting configures which
-    # kubernetes groups the users of this role will be assigned to.
-    # Note that you can refer to a SAML/OIDC trait via the "external" property bag.
-    # This allows you to specify Kubernetes group membership in an identity manager:
-    kubernetes_groups: ["system:masters", "{{external.trait_name}}"]]
-
-    # List of node labels a user will be allowed to connect to:
-    node_labels:
-      # A user can only connect to a node marked with 'test' label:
-      'environment': 'test'
-      # The wildcard ('*') means "any node"
-      '*': '*'
-      # Labels can be specified as a list:
-      'environment': ['test', 'staging']
-      # Regular expressions are also supported, for example, the equivalent
-      # of the list example above can be expressed as:
-      'environment': '^test|staging$'
-
-    kubernetes_labels:
-      # A user can only access prod environments
-      'env': 'prod'
-      # User can access any region in us-west, e.g us-west-1, us-west-2
-      'region': 'us-west-*'
-      'cluster_name': '^us.*\.example\.com$'
-
-    # Defines roles that this user can request.
-    # Needed for teleport's access request workflow
-    # https://goteleport.com/teleport/docs/enterprise/workflow/
-    request:
-      roles:
-      - dba
-
-    # List of allow-rules. See below for more information.
-    rules:
-    - resources: [role]
-      verbs: [list, create, read, update, delete]
-    - resources: [auth_connector]
-      verbs: [list, create, read, update, delete]
-    - resources: [session]
-      verbs: [list, read]
-    - resources: [trusted_cluster]
-      verbs: [list, create, read, update, delete]
-    - resources: [event]
-      verbs: [list, read]
-    - resources: [user]
-      verbs: [list,create,read,update,delete]
-    - resources: [token]
-      verbs: [list,create,read,update,delete]
-
-    # Moderated Sessions policy that dictates requirements for starting a session.
-    require_session_join:
-      # Defines the name of the policy. The name serves only as an
-      # identifier in logs and for organisation/categorisation.
-      - name: Auditor oversight
-        # Specifies an RBAC predicate that is used to define
-        # which users count against the required user count of the policy.
-        filter: 'contains(user.roles, "auditor")'
-        # The different session kinds this policy applies to.
-        kinds: ['k8s', 'ssh']
-        # A list of session participant modes that a participant must have
-        # one of in order to count against the policy.
-        modes: ['moderator']
-        # The minimum amount of users that need to match the filter expression
-        # in order to satisfy the policy.
-        count: 1
-
-    # Moderated Sessions policy that dictates the ability to join sessions
-    join_sessions:
-      # Defines the name of the policy. The name serves only as an
-      # identifier in logs and for organisation/categorisation.
-      - name: Auditor oversight
-        # Allows one to join sessions created by other users with these roles
-        roles : ['prod-access']
-        # The different session kinds this policy applies to.
-        kinds: ['k8s', 'ssh']
-        # The list of session participant modes the role may join the session as.
-        modes: ['moderator', 'observer']
-
-  # The deny section uses the identical format as the 'allow' section.
-  # The deny rules always override allow rules.
-  deny: {}
-```
+(!docs/pages/includes/role-spec.mdx!)

 The following variables can be used with `logins` and `windows_desktop_logins` fields:

@@ -414,7 +272,7 @@ allow:

 It is possible to further limit access to
 [shared sessions](../server-access/guides/tsh.mdx#sharing-sessions) and
-[session recordings](../architecture/nodes.mdx#session-recording).
+[session recordings](../architecture/nodes.mdx#ssh-session-recording).
 The examples below illustrate how to restrict session access only for the user
 who created the session.

@@ -1,230 +1,167 @@
 ---
-title: Teleport Authentication Service, SSH, and Kubernetes certificates
-description: This chapter explains the concept of a Teleport Auth Service and Certificate Authority (CA) to issue SSH and Kubernetes certificates.
-h1: Teleport Authentication Service
+title: Teleport Authentication
+description: This chapter explains how Teleport uses certificate authorities to authenticate users and services.
+h1: Teleport Authentication with Certificates
 ---

-This document outlines the Teleport Authentication Service and Certificate
-Management. It explains how Users and Nodes are identified and granted access to
-Nodes and Services.
+## Authentication

-## Authentication vs. Authorization
+Teleport handles both authentication and authorization.

-Teleport Auth handles both authentication and authorization. These topics are
-related but different, and they are often discussed jointly as "Auth".
+- Authentication is about proving an identity of a user or a service.
+- Authorization is proving access rights to something.

-**Authentication** is proving an identity. "I say I am Bob, and I really am Bob.
-See look I have Bob's purple hat." The job of an Authentication system is to
-define the criteria by which users must prove their identity. Is having a purple
-hat enough to show that a person is Bob? Maybe, maybe not. To identify users and
-nodes to Teleport Auth, we require them to present a cryptographically-signed
-certificate issued by the Teleport Auth Certificate Authority.
+This article covers authentication with short-lived certificates.

-**Authorization** is proving access to something: "Bob has a purple hat, but
-also a debit card and the correct PIN code. Bob can access a bank account with
-the number 814000001344. Can Bob get $20 out of the ATM?" The ATM's Authentication system would validate Bob's PIN Code, while the Authorization system would use a stored mapping from Bob to account #814000001344 to decide
-whether Bob could withdraw cash. Authorization defines and determines
-permissions that users have within a system, such as access to cash within a
-banking system, or data in a filesystem. Before users are granted access to
-nodes, the Auth Service checks their identity against a stored mapping in a
-database.
+## Short-Lived Certificates

-![Authentication and Authorization](../../img/authn_authz.svg)
+Certificate Authorities and short-lived certificates are the core of Teleport authentication.
+In Teleport at the start of every connection, a user or a service has to present a valid certificate issued by
+a trusted certificate authority. Clients always initiate mutual TLS or mutual SSH connections.

-## SSH certificates
+Teleport Certificate Authority issues short-lived x.509 certificates for web services, databases, kubernetes clusters,
+desktops and SSH certificates for OpenSSH-compatible servers.

-One can think of an SSH certificate as a "permit" issued and time-stamped by a
-trusted authority. In this case, the authority is the Auth Server's Certificate
-Authority. A certificate contains four important pieces of data:
+### Why certificates?
+
+- Certificates are tied to user or service identity. Any connection and action can be traced back to a user
+or a service.
+- Short-lived certificates automatically expire, there is no need to revoke them.
+- Certificates solve trust on first use (TOFU) problems. In a Teleport cluster, all servers have
+identities and certificates of their own. They will not allow a connection if a client certificate is signed by an
+untrusted certificate authority.
+- Certificates enable mutually authenticated channel - mTLS, mTLS mitigates a wide range of attacks - spoofing, on-path attacks, credential stuffing and others.
+- Certificates work better for large-scale deployments. Each server or service just needs to validate
+if the certificate has been signed with a valid certificate authority, and does not need to copy user
+credentials over to every service.
+
+<Notice type="tip">
+Teleport issues certificates that are good from a few hours to minutes before they auto-expire without any action.
+The shorter the duration for these certificates, the better.
+Ideally, certs should be issued only for the duration of a session.
+In practice, several hours or the duration of the workday are OK too.
+The expiry date in certificates can not be forged
+without invalidating the certificates, so any system can validate the certificate.
+</Notice>
+
+### X.509 certificates
+
+X.509 certificates are the same certificates you use when accessing websites with a browser. They bind
+identity to the public key with a certificate authority's signature.
+
+<Figure
+  align="center"
+  caption="Example of x.509 short-lived certs"
+>
+
+![x.509 certs](../../img/architecture/x509-cert@2x.svg)
+
+</Figure>
+
+Teleport uses x.509 certificates for Kubernetes, databases, web services and its own internal
+components - proxies, auth services to establish mutually authenticated TLS connections - mTLS.
+
+### OpenSSH certificates
+
+OpenSSH certificates are similar to X.509 (web) certificates and also bind identity of the user or a server
+to the public key with a certificate authority's signature.
+
+<Figure
+  align="center"
+  caption="Example of SSH short-lived certs"
+>
+
+![SSH certs](../../img/architecture/ssh-cert@2x.svg)
+
+</Figure>
+
+OpenSSH certificate contain metadata used to authenticate users and hosts:

 1. List of principals (identities) this certificate belongs to.
 2. Signature of the certificate authority who issued it.
 3. The expiration date, also known as "time-to-live" or simply TTL.
 4. Additional data, such as the node role, is stored as a certificate extension.

-## Authentication in Teleport
+### Making Time Work For You

-Teleport uses SSH certificates to authenticate nodes and users within a cluster.
+Expiry is a feature of certificates that makes time work in favor of security.
+SSH and X.509 certificates include an optional expiry date that is verified by
+servers in addition to a signature.

-Two CAs are used inside the Auth Server because nodes and users each need their own certificates. {/* TODO: Why? */}
-
- The **Node CA** issues certificates which identify a node (i.e. host, server,
-  computer). These certificates are used to add new nodes to a cluster and identify connections coming from the node.
- The **User CA** issues certificates which identify a User. These certificates are used to authenticate users when they try to connect to a cluster node.
-
-### Issuing Node certificates
-
-Node Certificates identify a node within a cluster and establish the permissions
-of the node to access other Teleport services. The presence of a signed
-certificate on a node makes it a cluster member.
-
-![Node Joins Cluster](../../img/node_join.svg)
-
-1. To join a cluster for the first time, a node must present a "join token" to the auth server. The token can be static (configured via config file) or a dynamic, single-use token generated by [`tctl nodes add`](../setup/reference/cli.mdx#tctl-nodes-add).
-
-<Admonition
-  type="tip"
-  title="Token TTL"
+<Figure
+  align="center"
+  caption="Example of SSH short-lived certs"
 >
-  When using dynamic tokens, their default time to live (TTL) is 30
-  minutes, but it can be reduced (not increased) via
-  [`tctl nodes add --ttl`](../setup/reference/cli.mdx#tctl-nodes-add) flag.
-</Admonition>

-2. When a new node joins the cluster, the auth server generates a new public/private keypair for the node and signs its certificate. This node certificate contains the node's role(s) (`proxy`, `auth` or `node`) as a certificate extension (opaque signed string).
+![Short lived certs](../../img/architecture/ssh-cert-short-lived@1.5x.svg)

-### Using Node certificates
+</Figure>

-![Node Authorization](../../img/node_cluster_auth.svg)
+In the diagram above, Alice gets a short lived SSH certificate, but the same rules apply to
+X.509 certificates issued by Teleport and used for Kubernetes, Databases, Web Apps and Desktops.

-All nodes in a cluster can connect to the [Auth Server's API](#auth-api) {/* Docs about this */}
-implemented as an HTTP REST service running over the SSH
-tunnel. This API connection is authenticated with the node certificate and the
-encoded role is checked to enforce access control. For example, a client
-connection using a certificate with only the `node` role won't be able to add
-and delete users. This client connection would only be authorized to get auth
-servers registered in the cluster.
+Teleport issues certificates that are good from a few hours to minutes before they auto-expire without any action.
+Instead of distributing revocation lists, Teleport relies on time to do the job for us.

-### Issuing user certificates
+<Notice type="tip">
+In some cases, certificate expiration is not fast enough, and all sessions have to be terminated immediately,
+for example during active security incident.
+For those cases, Teleport Proxy can terminate live connections using [session and identity locking](../access-controls/guides/locking.mdx).
+</Notice>

-![Client obtains new certificate](../../img/cert_invalid.svg)
+### Short-lived Certs For Users

-The Auth Server uses its User CA to issue user certificates. User certificates
-are stored on a user's machine in the `~/.tsh/keys/example.com` directory or also
-by the system's SSH agent if it is running.
+To issue a certificate to a user, Teleport opens login screen, issues a cert and delivers it back to a user's computer:

-1. To get permission to join a cluster for the first time a user must provide their username, password, and 2nd-factor token. Users can log in with [`tsh login`](../setup/reference/cli.mdx#tsh-login) or via the Web UI. The Auth server checks the username and password against its identity storage and checks the 2nd-factor token.
-2. If the correct credentials were offered, the Auth Server will generate a signed certificate and return it to the client. For users, certificates are stored in `~/.tsh` by default. If the client uses the Web UI the signed certificate is associated with a secure WebSocket session.
+We recommend using SSO with GitHub, Okta or any other identity provider and get a cert.

-In addition to a user's identity, user certificates also contain user roles and
-SSH options, like "permit-agent-forwarding" {/* TODO: link to config/set options here */}.
-This additional data is stored as a certificate extension and is protected by
-the CA signature.
+<Figure
+  align="center"
+  bordered="true"
+  caption="SSO exchange with short-lived certs"
+  >
+  
+![SSO exchange for short-lived certs](../../img/architecture/idp-sso-traits@1.5x.svg)
+</Figure>

-### Using user certificates
+### Short-lived Certs for Services

-![Client offers valid certificate](../../img/user_auth.svg)
+Deployment automation services, such as Jenkins, can use Teleport's Machine ID
+service to receive and renew certificates. Teleport Machine ID's bot runs alongside
+services and rotates SSH and X.509 certificates.

-When a client requests access to a node cluster, the Auth Server first checks
-that a certificate exists and hasn't expired. If it has expired, the client must
-re-authenticate with their username, password, and 2nd factor. If the
-certificate is still valid, the Auth Server validates the certificate's
-signature. The client is then granted access to the cluster. From here, the
-[Proxy Server](proxy.mdx) establishes a connection between client and node.
+<Figure
+  align="center"
+  bordered="true"
+  caption="Machine-ID certs"
+  >
+  
+![Certificates for services](../../img/architecture/certs-machine-id@1.8x.svg)
+</Figure>

-## Certificate rotation
+### Internal certificates

-By default, all user certificates have an expiration date, also known as the *time to live *(TTL). This TTL can be configured by a Teleport administrator. However, the node certificates issued by an Auth Server are valid indefinitely by default.
+Teleport internal services - Auth, Proxy and Nodes use certificates to identify themselves
+within a cluster. To join proxies and nodes to the cluster and receive certificates, admins should use
+[short-lived tokens or cloud identity services](../setup/admin/adding-nodes.mdx).

-Teleport supports certificate rotation, i.e. the process of invalidating all
-previously-issued certificates for nodes *and* users regardless of their TTL.
-Certificate rotation is triggered by [`tctl auth
-rotate`](../setup/reference/cli.mdx#tctl-auth-rotate). When this command is invoked by a Teleport
-administrator on one of a cluster's Auth Servers, the following happens:
+Unlike users and services, internal services receive long-lived certificates.

-1. A new certificate authority (CA) key is generated.
-2. The old CA will be considered valid *alongside* the new CA for a while. This period is called a *grace period*. {/* TODO: Link to config/defaults. */}
-3. During the grace period, all previously issued certificates will be considered valid, assuming their TTL isn't expired.
-4. After the grace period is over, the certificates issued by the old CA are no longer accepted.
-
-This process is repeated twice, once for the node CA and once for the user CA.
+To renew these certificates, admins should use certificate authority rotation, the process of invalidating all
+previously-issued certificates for nodes or users regardless of expiry and issuing a new ones,
+using a new certificate authority.

 Take a look at the [Certificate Rotation Guide](../setup/operations/ca-rotation.mdx) to
 learn how to do certificate rotation in practice.

-## Auth API
-
-{
-  /* TODO: Can we say more about this, abstract of routes provided */
-}
-
-Clients can also connect to the auth API through the Teleport proxy to use a limited subset of the API to discover the member nodes of the cluster.
-
-## Auth state
-
-The Auth service maintains state using a database of users, credentials,
-certificates, and audit logs. The default storage location is
-`/var/lib/teleport` or an [admin-configured storage destination](../setup/reference/backends.mdx).
-
-There are three types of data stored by the auth server:
-
- - **Cluster State** The auth server stores its own keys in a cluster state storage. All of cluster dynamic configuration is stored there as well, including:
-  - Node membership information and online/offline status for each node.
-  - List of active sessions.
-  - List of locally stored users
-  - RBAC configuration (roles and permissions).
-  - Other dynamic configuration.
- **Audit Log** When users log into a Teleport cluster, execute remote commands, and log out, that activity is recorded in the audit log. See Audit Log for more details. More on this in the [Audit Log section](../setup/reference/audit.mdx).
- **Recorded Sessions** When Teleport users launch remote shells via `tsh ssh` command, their interactive sessions are recorded and stored by the auth server. Each recorded session is a file that is saved in /var/lib/teleport by default but can also be saved in external storage, like an AWS S3 bucket.
-
-## Audit log
-
-The Teleport auth server keeps the audit log of SSH-related events that take
-place on any node within a Teleport cluster. Each node in a cluster emits audit
-events and submits them to the auth server. The events recorded include:
-
- Successful user logins
- Node IP addresses, Application, Database and Kubernetes FQDN
- Session time
- Session IDs
-
-<Admonition
-  type="warning"
-  title="Compatibility Warning"
->
-  Because all SSH events like `exec` or `session_start` are by default reported by the Teleport node service, they will not be logged if you are using OpenSSH `sshd` daemon on your nodes. [Recording proxy mode](proxy.mdx#recording-proxy-mode)
-</Admonition>
-
-Only an SSH server can report what's happening to the Teleport auth server.
-The audit log is a JSON file that is by default stored on the auth server's
-filesystem under `/var/lib/teleport/log`. The format of the file is documented
-in the [Admin Manual](../setup/reference/audit.mdx).
-
-Teleport users are encouraged to export the events into external, long term
-storage.
-
-<Admonition
-  type="tip"
-  title="Deployment Considerations"
->
-  If multiple Teleport auth servers are used
-  to service the same cluster (High Availability mode) a network file system must be used for
-  `/var/lib/teleport/log` to allow them to combine all audit events into the
-  same audit log. [Learn how to deploy Teleport in High Availability Mode.](../setup/reference/backends.mdx).
-</Admonition>
-
-## Storage back-ends
-
-Different types of cluster data can be configured with different storage
-back-ends as shown in the table below:
-
-| Data Type | Supported Back-ends | Notes |
-| - | - | - |
-| Cluster state | `dir`, `etcd`, `dynamodb`,`firestore` | Multi-server (High Availability) configuration is only supported using `etcd`, `dynamodb`, and `firestore` back-ends. |
-| Audit Log Events | `dir`, `dynamodb`, `firestore` | If `dynamodb` is used for the audit log events, `s3` back-end **must** be used for the recorded sessions. |
-| Recorded Sessions | `dir`, `s3` | `s3` is mandatory if `dynamodb` is used for the audit log. For Google Cloud storage use `audit_sessions_uri: 'gs://` |
-
-<Admonition
-  type="tip"
-  title="Note"
->
-  The reason Teleport designers split the audit log events and the recorded sessions into different back-ends is because of the nature of the data. A recorded session is a compressed binary stream (blob) while the event is a well-defined JSON structure. `dir` works well enough for both in small deployments, but large clusters require specialized data stores: S3 is perfect for uploading session blobs, while DynamoDB or `etcd` are better suited to store the cluster state.
-</Admonition>
-
-The combination of DynamoDB + S3 is especially popular among AWS users because
-it allows them to run Teleport clusters completely devoid of local state.
-
-<Admonition
-  type="tip"
-  title="NOTE"
->
-  For High Availability in production, a Teleport cluster can be
-  serviced by multiple auth servers running in sync. Check [High Availability configuration](../setup/reference/backends.mdx) in the Admin Guide.
-</Admonition>
+<Notice type="tip">
+To quickly lock out the node, proxy or auth service that may be compromised without rotating the entire
+cluster certificates, use node [session and identity locking](../access-controls/guides/locking.mdx).
+</Notice>

 ## More concepts

 - [Architecture Overview](overview.mdx)
- [Teleport Users](users.mdx)
+- [Authorization](authorization.mdx)
 - [Teleport Nodes](nodes.mdx)
 - [Teleport Proxy](proxy.mdx)
@@ -0,0 +1,381 @@
+---
+title: Teleport Authorization
+description: This chapter explains how Teleport authorizes users and roles.
+h1: Teleport Authorization
+---
+
+## Authorization
+
+Teleport handles both authentication and authorization.
+
+- Authentication is about proving an identity of a user or a service.
+- Authorization is proving access rights to something.
+
+This article covers authorization of users and services with RBAC.
+
+## Users and Roles
+
+Teleport supports several types of user accounts:
+
+- Interactive and non-interactive.
+- Local and external.
+
+Each user is associated with one or several roles after successful authentication.
+
+### Interactive users
+
+Interactive users can be local or external.
+Local user accounts store login credentials - password hash and MFA device data in Teleport's backend.
+External user accounts authenticate with a third-party identity provider using SSO protocols - OAuth 2.0, OIDC or SAML.
+
+#### External users from SSO providers
+
+Let's review the example Alice who is authenticating using SSO provider of her organization
+with Teleport:
+
+![Role mapping](../../img/architecture/role-mapping@1.5x.svg)
+
+<Notice type="tip">
+Every time SSO user logs in, Teleport creates a temporary user account record
+that automatically expires with SSO session and logs audit log entries.
+
+Teleport creates this record to avoid name collisions with local users.
+</Notice>
+
+#### External users from other clusters
+
+A user could be external to the Teleport cluster, if another cluster or certificate authority issues a certificate
+that this cluster trusts. In this case, Teleport activates [trusted cluster mapping logic](./trustedclusters.mdx#role-mapping).
+
+#### Local interactive users
+
+Local interactive users have a record in Teleport's backend with credentials.
+
+A cluster administrator have to create account entries for every Teleport user with
+[`tctl users add`](../setup/reference/cli.mdx) or API call.
+
+Every local Teleport User must be associated with a list of one or more roles.
+This list is called "role mappings".
+
+### Non-interactive users
+
+Teleport supports non-interactive users for automation services, e.g. Jenkins or micro-services
+running in your organization.
+
+### Local non-interactive users
+
+Local non-interactive users also have a user entry that maps their name to roles,
+but they do not have credentials stored in the database.
+Non-interactive users have to use Teleport's machine ID product to receive and renew certificates.
+Teleport Machine ID's bot runs alongside services and rotates SSH and X.509 certificates on behalf
+of non-interactive users:
+
+<Figure
+  align="center"
+  bordered="true"
+  caption="Machine-ID certs"
+  >
+  
+![Certificates for services](../../img/architecture/certs-machine-id@1.8x.svg)
+</Figure>
+
+### External non-interactive users
+
+External non-interactive users behave just like local ones, but it is another
+cluster or certificate authority that issues certificates for them.
+
+They do not have local user records in Teleport backend. Teleport activates
+[trusted cluster mapping logic](./trustedclusters.mdx#role-mapping) to support this use case.
+
+## Role Based Access Control
+
+Every Teleport user is assigned one or several roles that govern access to resources and Teleport's API.
+
+### Allow and Deny Rules
+
+Each Teleport role works by having two lists of rules: `allow` rules and `deny` rules:
+
+- Everything is denied by default.
+- Deny rules get evaluated first and take priority.
+- A rule consists of two parts: the resources and verbs.
+
+Here's an example of an allow rule describing a list verb applied to the sessions resource.
+It means "allow users of this role to see a list of recorded SSH or Kubernetes sessions".
+
+```yaml
+allow:
+  - resources: [session]
+    verbs: [list]
+```
+
+### Principals
+
+Roles define what principals (e.g. Linux OS users or Kubernetes group) users assigned
+to the role are allowed to assume:
+
+```yaml
+spec:
+  allow:
+    # The logins array defines the OS/UNIX logins a user is allowed to use.
+    logins: [ubuntu]
+    # Kubernetes groups defines what kubernetes groups a user is allowed to assume.
+    kubernetes_groups: [viewer]
+```
+
+In case if a user has many roles, the list of principals is merged in one set.
+
+### Labels
+
+Role labels define what resources rules in the role apply to. For example, let's
+review a role that specifies access for SSH nodes and kubernetes clusters:
+
+```yaml
+spec:
+  allow:
+    # List of node labels a user will be allowed to connect to:
+    node_labels:
+      # Regular expressions are also supported, for example, the equivalent
+      # of the list example above can be expressed as:
+      'environment': '^test|staging$'
+
+    kubernetes_labels:
+      # User can access any region in us-west, e.g us-west-1, us-west-2
+      'region': 'us-west-*'
+      'cluster_name': '^us.*\.example\.com$'
+```
+
+Here is how labels, allow rules and principals are applied:
+
+- For `allow` rule to match, all labels in the rule should match,
+for example, in the Kubernetes rule above, both `region` and `cluster_name` should match.
+- For `deny` rule to match, any label in the rule could match.
+
+**Principals and labels**
+
+Let's assume Alice is assigned two roles: `dev` and `prod`:
+
+Dev role allows SSH access as `root` and unrestricted access to kubernetes as `system:masters` for
+any kubernetes cluster or node with labels matching 'test' or 'stage'.
+
+```yaml
+metadata:
+  name: dev
+spec:
+  allow:
+    logins: [root]
+    kubernetes_groups: ['system:masters']
+    # List of node labels a user will be allowed to connect to:
+    node_labels:
+       'environment': ['test', 'stage']
+    kubernetes_labels:
+       'environment': ['test', 'stage']
+```
+
+Prod role allows SSH access as `ubuntu` and `view` access to kubernetes for
+any kubernetes cluster or node with labels matching 'prod'
+
+```yaml
+metadata:
+  name: prod
+spec:
+  allow:
+    logins: [ubuntu]
+    kubernetes_groups: ['view']
+    node_labels:
+       'environment': ['prod']
+    kubernetes_labels:
+       'environment': ['prod']
+```
+
+Here is how Teleport will evaluate Alice's access:
+
+- Alice can SSH as root to server labeled as `test` or `stage`
+- Alice can not SSH as root to server labeled as `prod`, because prod role
+only allows access as `ubuntu` to `prod`-labeled servers.
+
+The same applies to Kubernetes:
+
+- Alice can access kubernetes cluster as `system:masters` if it's labeled as `test` or `stage`.
+- Alice can access kubernetes clusters only as a `view` role if it's labeled as `prod`.
+
+
+### Role templates
+
+Roles support template variables. Here is a role snippet that explains
+how variables are interpolated.
+
+```yaml
+spec:
+  # The allow section declares a list of resource/verb combinations that are
+  # allowed for the users of this role. By default, nothing is allowed.
+  allow:
+    # internal.logins - will be interpolated from local user's traits -
+    # properties you can assign when creating a user.
+    logins: ['{{internal.logins}}']
+
+    # kubernetes_groups specifies Kubernetes groups a user with this role will assume.
+    # You can refer to a SAML/OIDC trait via the "external" property bag.
+    # This allows you to specify Kubernetes group membership in an identity manager:
+    kubernetes_groups: ['{{external.groups}}']
+```
+
+<Notice type="tip">
+Any role that uses variable interpolation is treated as a role template.
+You can add interpolation to any role spec.
+</Notice>
+
+**Variable interpolation rules*
+
+- If `external.groups` is a list that contains `["dev", "prod"]` the expression `["{{external.groups}}"]`
+will interpolate to list `["dev", "prod"]`.
+- If `external.groups` is a variable that equals `"dev"` the expression `["{{external.groups}}"]`
+will interpolate to `["dev"]`.
+- If `external.groups` is missing, the expression `"{{external.groups}}"` will evaluate into empty string `""`.
+You can use predicate language function calls in templates, e.g. `{{email.local(external.foo)}}`.
+- You can combine string prefixes and values, for example: `"IAM#{{regexp.replace(external.foo, "^bar-(.*)$", "$1")}};"`.
+- Invalid expressions will be ignored, e.g. `external.foo}}` will be skipped, just as invalid function calls.
+- Invalid values will be omitted, for example `-foo` is not a valid Unix login, so if variable `external.foo` equals
+`"-foo"`, it will be omitted in `logins: ["{{external.foo}}"]`.
+
+**How role templates are evaluated**
+
+Role templates are evaluated at the time of access to any resource either by proxy or node.
+Every Teleport component - proxy, auth server or node has up to date copy of all roles.
+
+Let's review a case with the following role template:
+
+```yaml
+metadata:
+  name: devs
+spec:
+  allow:
+    kubernetes_groups: ["{{external.k8s_groups}}"]
+    kubernetes_labels:
+       "env": ["{{external.env}}"]
+```
+
+User Alice authenticates with Teleport and receives the following variables from
+the identity provider:
+
+```
+k8s_groups: ["view", "edit"]
+env: ["stage"]
+```
+
+These variables get encoded in the X.509 certificate as extensions.
+
+When proxy authorizes the attempt to connect to the Kubernetes cluster it interpolates
+the role template and the variables, and gets:
+
+```yaml
+metadata:
+  name: devs
+spec:
+  allow:
+    kubernetes_groups: ["view", "edit"]
+    kubernetes_labels:
+       "env": ["stage"]
+```
+
+Finally, the proxy applies the resulting role to the kubernetes cluster Alice tries to
+access and checks it against cluster. If the cluster has labels  `"env": "stage"`
+the attempt succeeds, otherwise it fails.
+
+### Role conditions
+
+The example below illustrate how to restrict session access only for the user who created the session
+using role conditions:
+
+```yaml
+kind: role
+metadata:
+  name: only-own-sessions
+spec:
+  allow:
+    rules:
+    # Users can only view session recordings for sessions in which they
+    # participated.
+    - resources: [session]
+      verbs: [list, read]
+      where: contains(session.participants, user.metadata.name)
+```
+
+<Notice type="tip">
+You can use `where` fields in all resource rules. Check out [the full role reference](../access-controls/reference.mdx) contains full role spec for details.
+</Notice>
+
+### Role options
+
+Alongside `allow` and `deny` rules, roles control a variety of options, for example:
+
+```
+kind: role
+version: v5
+metadata:
+  name: relaxed
+spec:
+  # options specify connection, in case if user has multiple non-default
+  # conflicting options, teleport chooses the least permissive value.
+  options:
+    # max_session_ttl defines the TTL (time to live) of certificates
+    # issued to the users with this role.
+    max_session_ttl: 8h
+    # lock sets locking mode for user of this role,
+    # valid values are "strict" or "best_effort"
+    lock: strict
+```
+
+In case if user has multiple roles that specify conflicting options, for example,
+role `relaxed` sets the `max_session_ttl` to `8h` and `restricted` that sets `max_session_ttl`
+to `4h`, most secure value will be used, in this case Teleport will choose to limit sessions to 4 hours.
+
+Teleport applies the same logic to other values, for example if two roles specify both `strict` and `best_effort`
+options, Teleport will choose `strict` option.
+
+### Just in Time Access Requests
+
+<ScopedBlock
+  scope={["oss"]}
+>
+
+<Notice type="tip">
+  The full version of Just In Time Access Requests is available only in Teleport Cloud or Enterprise.
+</Notice>
+
+</ScopedBlock>
+
+Roles allow requesting elevated privileges - other roles or individual resources.
+
+Roles control who can review requests for privileges and define how many approvals
+or rejections are required:
+
+```yaml
+spec:
+  allow:
+    # review_requests allows a user holding this role
+    # to approve or deny access requests
+    review_requests:
+      roles: ['dbadmin']
+
+    # request allows a user user request roles matching
+    # expressions below
+    request:
+      # the `roles` list can be a mixture of literals and wildcard matchers
+      roles: ['common', 'dev-*']
+      # thresholds specifies minimum amount of approvers and deniers,
+      # defaults to 1 for both
+      thresholds:
+        # requires at least two qualifying approvers and at least one denier.
+        - approve: 2
+          deny: 1
+```
+
+## Next steps
+
+- [Access Control Reference](../access-controls/reference.mdx).
+- [Teleport Predicate Language](../setup/reference/predicate-language.mdx).
+- [Access Requests Guides](../enterprise/workflow/index.mdx)
+- [Architecture Overview](overview.mdx)
+- [Teleport Auth](authentication.mdx)
+- [Teleport Nodes](nodes.mdx)
+- [Teleport Proxy](proxy.mdx)
@@ -1,43 +1,50 @@
 ---
-title: Teleport Nodes
-description: This chapter explains the concept of a Teleport Node and Teleport manages SSH and Kubernetes nodes.
-h1: Teleport Nodes
+title: Teleport SSH Nodes
+description: This chapter explains the concept of a Teleport Node and how Teleport manages SSH.
+h1: Teleport SSH Nodes
 ---

-Teleport calls any computing device (server, VM, AWS instance, etc) a "node".
+## The SSH Node service

-## The Node service
+The Teleport Node service is optional. You can use it to replace OpenSSH on your infrastructure.
+Here is why we recommend Teleport Node service instead of OpenSSH:

-A node becomes a Teleport Node when the node joins a cluster with a "join" token. Read about how nodes are issued certificates in the [Auth Guide](authentication.mdx#issuing-node-certificates).
+- The node service supports BPF recording of all syscalls, network calls and files accessed during SSH session.
+- It can record terminal sessions.
+- It provides automatic registration, certificate and certificate authority rotation,
+- It can provision OS user and update sudoers files according to teleport roles.
+- You can connect nodes to proxies with outbound persistent tunnels, for your IoT lab or remote infrastructure.

-![Node joins a cluster](../../img/node_join.svg)
+Just like with OpenSSH, the `node` service provides SSH access to every node with any clients supporting client SSH certificates:

-A Teleport Node runs the [`teleport`](../setup/reference/cli.mdx#teleport) daemon with the `node` role. This process handles incoming connection requests, authentication, and remote command execution on the node, similar to the function of OpenSSH's `sshd`.
+- [OpenSSH: `ssh`](../server-access/guides/openssh.mdx)
+- [Teleport CLI client: `tsh ssh`](../setup/reference/cli.mdx#tsh-ssh)
+- [Teleport Proxy UI](./proxy.mdx) accessed via a web browser.
+- Ansible and other SSH compatible clients.

-![Node Service ping API](../../img/node_service_api.svg)
+## Joining Nodes

-All cluster Nodes keep the Auth Server updated on their status with periodic ping messages. They report their IP addresses and the values of their assigned labels. Nodes can access the list of all Nodes in their cluster via the [Auth Server API](authentication.mdx#auth-api).
+A node candidate becomes a Teleport Node it joins a cluster - authenticates itself to receive cluster certificate.
+
+![Node joins a cluster](../../img/architecture/node-registration@1.2x.svg)
+
+All cluster Nodes keep the Auth Server updated on their status with periodic ping messages.
+They report their IP addresses and the values of their assigned labels.
+Clients can access the list of all Nodes in their cluster via the Auth Server API or CLI.

 <Admonition
  type="tip"
  title="Tip"
 >
-  In most environments, we advise replacing the OpenSSH daemon `sshd` with the Teleport Node Service unless there are existing workflows relying on `ssh` or in special cases such as embedded devices that can't run custom binaries.
+Nodes can register with Auth servers directly, or use proxies to establish the connection to auth servers.
+The latter is helpful if you have multiple proxies and nodes all over the world.
 </Admonition>

-The `node` service provides SSH access to every node with all of the following clients:
+## SSH Host certificate

- [OpenSSH: `ssh`](../server-access/guides/openssh.mdx)
- [Teleport CLI client: `tsh ssh`](../setup/reference/cli.mdx#tsh-ssh)
- [Teleport Proxy UI](proxy.mdx#web-to-ssh-proxy) accessed via a web browser.
+Node's identity is represented by SSH host certificate it receives after registering withing the cluster:

-Each client is authenticated via the [Auth Service](authentication.mdx#authentication-in-teleport) before being granted access to a Node.
-
-## Node identity on a cluster
-
-Node Identity is defined on the Cluster level by the certificate a node possesses.
-
-![Node Identity](../../img/node_identity.svg)
+![Host certificate](../../img/architecture/ssh-host-cert@1.2x.svg)

 This certificate contains information about the node including:

@@ -45,9 +52,9 @@ This certificate contains information about the node including:
 - A **nodename**, which defaults to `hostname` of the node, but can be configured.
 - The **cluster_name**, which defaults to the `hostname` of the auth server, but can be configured
 - The node **role** (i.e. `node,proxy`) encoded as a certificate extension
- The cert **TTL** (time-to-live)
+- The cert **Expiry time**

-A Teleport Cluster is a set of one or more machines whose certificates are signed by the same certificate authority (CA) operating in the Auth Server. A certificate is issued to a node when it joins the cluster for the first time. Learn more about this process in the [Auth Guide](authentication.mdx#authentication-in-teleport).
+A Teleport Cluster is a set of one or more machines whose certificates are signed by the same certificate authority (CA) operating in the Auth Server. A certificate is issued to a node when it joins the cluster for the first time.

 <Admonition
  type="warning"
@@ -58,26 +65,33 @@ A Teleport Cluster is a set of one or more machines whose certificates are signe

 ## Connecting to Nodes

-When a client requests access to a Node, authentication is always performed
-through a cluster proxy. When the proxy server receives a connection request
-from a client it validates the client's credentials with the Auth Service. Once
-the client is authenticated the proxy attempts to connect the client to the
-requested Node.
+Nodes support two modes - a standard mode and a reverse tunnel mode.

-There is a detailed walk-through of the steps needed to initiate a connection to
-a node in the [Architecture Overview](overview.mdx).
+In standard mode, nodes act like OpenSSH servers that
+only accept client SSH certificates. Users can connect to nodes through Proxy as a jump-host
+or directly:

-![Proxy Connection between client and node](../../img/proxy_client_connect.svg)
+![Standard Mode](../../img/architecture/ssh-direct-mode@1.2x.svg)
+
+In reverse tunnel mode, nodes establish reverse tunnels back to proxy. Nodes
+do not bind to any interface on the host, making sure the connection is only possible
+through proxies:
+
+![Tunnel Mode](../../img/architecture/ssh-tunnel-mode@1.2x.svg)
+
+<Notice type="tip">
+You can mix both modes in the same cluster, depending on your use case.
+For example, you can have several IOT devices joining the cluster via reverse tunnel
+and a large fleet of servers in the internal network using standard mode.
+</Notice>

 ## Cluster state

 Cluster state is stored in a central storage location configured by the Auth
-Server. This means that each node is completely stateless and holds no secrets
+Server. Each node (or proxy) is stateless and holds no secrets
 such as keys or passwords.

-![Cluster State](../../img/cluster_state.svg)
-
-The cluster state information stored includes:
+The cluster state includes:

 - Node membership information and online/offline status for each node.
 - List of active sessions.
@@ -85,14 +99,14 @@ The cluster state information stored includes:
 - RBAC configuration (roles and permissions).
 - Dynamic configuration.

-Read more about what is stored in the [Auth Guide](authentication.mdx#auth-state)
-
-## Session recording
+## SSH Session recording

 By default, nodes submit SSH session traffic to the Auth server
 for storage. These recorded sessions can be replayed later via `tsh play`
 command or in a web browser.

+### SSH node recording
+
 Some Teleport users assume that audit and session recording happen by default
 on the Teleport proxy server. This is not the case in default configuration
 because a proxy cannot see the encrypted traffic, it is encrypted end-to-end,
@@ -100,22 +114,44 @@ i.e. from an SSH client to an SSH server/node, see the diagram below:

 ![session-recording-diagram](../../img/session-recording.svg)

-However, starting from Teleport 2.4, it is possible to configure the
-Teleport proxy to enable "recording proxy mode".
+### Proxy recording mode 

-## Trusted Clusters
+In this mode, the proxy terminates (decrypts) the SSH connection using the
+certificate supplied by the client via SSH agent forwarding and then establishes
+its own SSH connection to the final destination server, effectively becoming an
+authorized "man in the middle". This allows the proxy server to forward SSH
+session data to the auth server to be recorded, as shown below:
+
+![recording-proxy](../../img/recording-proxy.svg)
+
+The recording proxy mode, although *less secure*, was added to allow Teleport
+users to enable session recording for OpenSSH's servers running `sshd`, which is
+helpful when gradually transitioning large server fleets to Teleport.
+
+We consider the "recording proxy mode" to be less secure for two reasons:
+
+1. It grants additional privileges to the Teleport proxy. In the default mode,
+   the proxy stores no secrets and cannot "see" the decrypted data. This makes a
+   proxy less critical to the security of the overall cluster. But if an
+   attacker gains physical access to a proxy Node running in the "recording"
+   mode, they will be able to see the decrypted traffic and client keys stored in the proxy's process memory.
+2. Recording proxy mode requires SSH Agent Forwarding. Agent Forwarding is required because without it, a proxy will not be able to establish the 2nd connection to the destination Node.
+
+However, there are advantages of proxy-based session recording too. When
+sessions are recorded at the Nodes, a root user can add iptables rules to
+prevent sessions logs from reaching the Auth Service. With sessions recorded at
+the proxy, users with root privileges on Nodes have no way of disabling the
+audit.
+
+See the [reference](../setup/reference/audit.mdx#recorded-sessions) to learn how to turn
+on the recording proxy mode. Note that the recording mode is configured on the
+Auth Service.

-Teleport Auth Service can allow 3rd party users or nodes to connect to cluster
-nodes if their certificates are signed by a trusted CA. A *trusted cluster* is
-a public key of the trusted CA. It can be configured via `teleport.yaml` file.

-{
-  /* TODO: incomplete, write more on this */
-}

 ## More concepts

 - [Architecture Overview](overview.mdx)
- [Teleport Users](users.mdx)
- [Teleport Auth](authentication.mdx)
+- [Teleport Authentication](authentication.mdx)
+- [Teleport Authorization](authorization.mdx)
 - [Teleport Proxy](proxy.mdx)
@@ -1,254 +1,133 @@
 ---
 title: Teleport Architecture Overview
-description: Basic concepts and architecture of Teleport. What is an SSH cluster? How certificate-based SSH authentication works? How does SSH auditing work?
-h1: Architecture Introduction
+description: High level overview of concepts and architecture of Teleport.
+h1: Architecture Overview
 ---

+<Notice type="tip">
 This guide is for those looking for a deeper understanding of Teleport. If you
 are looking for hands-on instructions on how to set up Teleport for your team,
 check out the [Admin Guide](../setup/admin.mdx)
+</Notice>

 ## What makes Teleport different

- Teleport replaces legacy keys and shared secrets with short-lived X.509 and SSH certificates
-  for services and users.
- It proxies and inspects SSH, Kubernetes, Web, and Database protocols.
-  For example for SSH, it controls the session from the start
-  and captures a session recording and in-kernel system calls using BPF.
- It removes a need for VPN and can connect multiple regions and organizations
-  in a decentralized network using mutual TLS and SSH tunnels.
+- Teleport replaces legacy keys, passwords and shared secrets with short-lived X.509 and SSH certificates
+  for services and users accessing your infrastructure.
+- It proxies and inspects SSH, Kubernetes, Web, Database and Desktop access protocols.
+- It removes a need for VPN and connects multiple regions and organizations
+in a decentralized network using mutual TLS and SSH tunnels.

-## Design principles
+## Core Components

-Teleport was designed under the following principles:
+The key concept of Teleport's architecture is a cluster.
+A Teleport cluster consists of the Teleport Auth Service, Teleport Proxy Service and optional Teleport Agents.

- **Off the Shelf Security**: Teleport does not re-implement any security primitives and uses well-established, popular implementations of the encryption and network protocols.
- **Open Standards**: There is no security through obscurity. Teleport is fully
-  compatible with existing and open standards and other software, including
-  [OpenSSH](../server-access/guides/openssh.mdx).
- **Cluster-Oriented Design**: Teleport is built for managing clusters, not individual servers. In practice this means that hosts and users
-  have cluster memberships. Identity management and authorization happen on a
-  cluster level.
- **Built for Teams**: Teleport was created under the assumption of multiple teams operating on several disconnected clusters. Example use cases might be production-vs-staging environment, or a cluster-per-customer or cluster-per-application basis.
+Cluster controls access to resources - Linux or Windows servers, databases, Kubernetes clusters,
+Windows desktops, cloud services and consoles, internal web applications and services.

-This doc introduces the basic concepts of Teleport so you can get started
-managing access!
+<Notice type="tip">
+To create a minimal Teleport cluster, you have to run two services:
+Teleport Auth Service and Teleport Proxy Service. For your home lab,
+you can run both services as a one binary and process.
+</Notice>
+
+### Teleport Auth Service
+
+The auth service controls certificate authority of the cluster.
+It uses managed back-ends and HSM to store the certificate authority private keys.
+The auth service issues certificates to clients and maintains the audit log.
+
+<Figure
+  align="center"
+  bordered="false"
+  caption="Auth service"
+>
+
+![Auth service](../../img/architecture/auth.png)
+
+</Figure>
+
+<Notice type="tip">
+The auth service uses HTTPS and accepts client certificates for authentication.
+You don't have to deploy it on a private network, but it's a good practice to restrict network access to its port
+for defense in depth.
+</Notice>
+
+Here are some key facts about the auth service:
+
+- It is the only service that has to be connected to the backend for audit and state storage.
+All other services are stateless and always interact with auth service GRPC API, never
+directly with the backend.
+- This is why you can safely limit access to the backend to the auth service only.
+- You can run multiple auth services in the cluster for high availability.
+
+### Teleport Proxy Service
+
+The proxy service allows access to cluster resources from the outside.
+It is the only service that has to be available from any user-facing network.
+All public users and external services most of the time connect to the proxy.
+
+<Figure
+  align="center"
+  bordered="false"
+  caption="Proxy service"
+>
+
+![Proxy service](../../img/architecture/proxy.png)
+
+</Figure>
+
+<Notice type="tip">
+In its minimal configuration, the proxy service can multiplex all connections on one port and protocol, HTTPS.
+</Notice>
+
+<Notice type="tip">
+In some cases, e.g. break-glass recovery scenarios, and if allowed by configuration, clients can bypass proxies and
+connect to resources with client certificates directly. Proxies add benefits, such as connection control,
+routing and tunneling but are not a required component for connections!
+</Notice>
+
+### Teleport Node Service
+
+The Teleport Node service is optional. You can use it to replace OpenSSH on your infrastructure.
+Here is why we recommend Teleport Node service instead of OpenSSH:
+
+- The node service supports BPF recording of all syscalls, network calls and files accessed during SSH session.
+- It can record terminal sessions.
+- It provides automatic registration, certificate and certificate authority rotation.
+- It can provision OS user and update sudoers files according to teleport roles.
+- You connect nodes to the proxy using outbound persistent tunnels, for your IoT lab or
+remote infrastructure.

 ## Definitions

-Here are definitions of the key concepts you will use in Teleport.
+Here are some of the key concepts we use in Teleport.

 | Concept | Description |
 | - | - |
-| Node | A node is a "server", "host" or "computer". Users can create shell sessions to access nodes remotely. |
-| User | A user represents someone (a person) or something (a machine) who can perform a set of operations on a node. |
-| Cluster | A cluster is a group of nodes that work together and can be considered a single system. Cluster nodes can create connections to each other, often over a private network. Cluster nodes often require TLS authentication to ensure that communication between nodes remains secure and comes from a trusted source. |
-| Certificate Authority (CA) | A Certificate Authority issues SSL certificates in the form of public/private keypairs. |
-| [Teleport Node](nodes.mdx) | A Teleport Node is a regular node that is running the Teleport Node service. Teleport Nodes can be accessed by authorized Teleport Users. A Teleport Node is always considered a member of a Teleport Cluster, even if it's a single-node cluster. |
-| [Teleport User](users.mdx) | A Teleport User represents someone who needs access to a Teleport Cluster. Users have stored usernames and passwords, and are mapped to OS users on each node. User data is stored locally or in an external store. |
-| Teleport Cluster | A Teleport Cluster is comprised of one or more nodes, each of which holds certificates signed by the same [Auth Server CA](authentication.mdx). The CA cryptographically signs the certificate of a node, establishing cluster membership. |
-| [Teleport CA](authentication.mdx) | Teleport operates two internal CAs as a function of the Auth service. One is used to sign User certificates and the other signs Node certificates. Each certificate is used to prove identity, cluster membership, and manage access. |
-
-## Teleport services
-
-Teleport uses three services which work together: [Nodes](nodes.mdx),
-[Auth](authentication.mdx), and [Proxy](proxy.mdx).
-
-[**Teleport Nodes**](nodes.mdx) are servers that can be accessed remotely with
-SSH. The Teleport Node service runs on a machine and is similar to the `sshd`
-daemon you may be familiar with. Users can log in to a Teleport Node with all
-of the following clients:
-
- [OpenSSH: `ssh`](../server-access/guides/openssh.mdx) (works on Linux, macOS and Windows)
- [Teleport CLI client: `tsh ssh`](../setup/reference/cli.mdx#tsh-ssh) (works on Linux, macOS and Windows)
- [Teleport Proxy UI](proxy.mdx#web-to-ssh-proxy) accessed via any modern web browser (including Safari on iOS and Chrome on Android)
-
-[**Teleport Auth**](authentication.mdx) authenticates Users and Nodes, authorizes User
-access to Nodes, and acts as a CA by signing certificates issued to Users and
-Nodes.
-
-[**Teleport Proxy**](proxy.mdx) forwards User credentials to the [Auth
-Service](authentication.mdx), creates connections to a requested Node after successful
-authentication, and serves a [Web UI](proxy.mdx#web-to-ssh-proxy).
-
-## Basic architecture overview
-
-The numbers correspond to the steps needed to connect a client to a node. These
-steps are explained below the diagram.
-
-<Admonition
-  type="warning"
-  title="Caution"
->
-  The teleport daemon calls services "roles" in the CLI
-  client. The `--roles` flag has no relationship to concept of [User Roles](users.mdx#user-roles) or
-  permissions.
-</Admonition>
-
-![Teleport Overview](../../img/overview.svg)
-
-1. Initiate Client Connection
-2. Authenticate Client
-3. Connect to Node
-4. Authorize Client Access to Node
-
-<Admonition
-  type="tip"
-  title="Tip"
->
-  In the diagram above we show each Teleport service separately for clarity, but Teleport services do not have to run on separate nodes.
-  Teleport can be run as a binary on a single-node cluster with no external storage backend. We demonstrate this minimal setup in the [Getting Started Guide](../getting-started.mdx).
-</Admonition>
-
-## Detailed architecture overview
-
-Here is a detailed diagram of a Teleport Cluster.
-
-The numbers correspond to the steps needed to connect a client to a node. These
-steps are explained in detail below the diagram.
-
-![Teleport Everything](../../img/everything.svg)
-
-### 1: Initiate client connection
-
-![Client offers certificate](../../img/client_initiate.svg)
-
-The client tries to establish an SSH connection to a proxy using the CLI
-interface or a web browser. When establishing a connection, the client offers
-its certificate. Clients must always connect through a proxy for two reasons:
-
-1. Individual nodes may not always be reachable from outside a secure network.
-
-2. Proxies always record SSH sessions and keep track of active user sessions.
-
-   This makes it possible for an SSH user to see if someone else is connected to
-   a node she is about to work on.
-
-### 2: Authenticate client certificate
-
-![Client offers valid certificate](../../img/cert_ok.svg)
-
-The proxy checks if the submitted certificate has been previously signed by the
-auth server.
-
-![Client obtains new certificate](../../img/cert_invalid.svg)
-
-If there was no certificate previously offered (first time log in) or if the certificate has expired, the proxy denies the connection and asks the client to
-login interactively using a password and a 2nd factor if enabled.
-
-Teleport supports
-[Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en),
-[Authy](https://www.authy.com/), or another
-[TOTP](https://en.wikipedia.org/wiki/Time-based_One-time_Password_algorithm)
-generator. The password + 2nd factor are submitted to a proxy via HTTPS,
-therefore it is critical for a secure configuration of Teleport to install a
-proper HTTPS certificate on a proxy.
-
-<Admonition
-  type="warning"
-  title="Warning"
->
-  Do not use self-signed SSL/HTTPS certificates in production!
-</Admonition>
-
-If the credentials are correct, the auth server generates and signs a new
-certificate and returns it to the client via the proxy. The client stores this certificate
-and will use it for subsequent logins. The certificate will automatically expire after
-12 hours by default. This [TTL](https://en.wikipedia.org/wiki/Time_to_live) can be [configured](../setup/reference/cli.mdx#tctl-users-add)
-to another value by the cluster administrator.
-
-### 3: Lookup Node
-
-![Node lookup](../../img/node_lookup.svg)
-
-At this step, the proxy tries to locate the requested node in a cluster. There
-are three lookup mechanisms a proxy uses to find the node's IP address:
-
-1. Uses DNS to resolve the name requested by the client.
-2. Asks the Auth Server if there is a Node registered with this `nodename`.
-3. Asks the Auth Server to find a node (or nodes) with a label that matches the requested name.
-
-If the node is located, the proxy establishes the connection between the client
-and the requested node. The destination node then begins recording the session,
-sending the session history to the auth server to be stored.
-
-<Admonition
-  type="note"
-  title="Note"
->
-  Teleport may also be configured to have the session recording
-  occur on the proxy, see [Audit Reference](../setup/reference/audit.mdx) for more
-  information.
-</Admonition>
-
-### 4: Authenticate Node certificate
-
-![Node Membership Authentication](../../img/node_cluster_auth.svg)
-
-When the node receives a connection request, it checks with the Auth Server to
-validate the node's certificate and validate the Node's cluster membership.
-
-If the node certificate is valid, the node is allowed to access the Auth Server
-API which provides access to information about nodes and users in the cluster.
-
-### 5: Grant user Node access
-
-![User Granted Node Access](../../img/user_node_access.svg)
-
-The node requests the Auth Server to provide a list of [OS users (user
-mappings)](../setup/admin/users.mdx) for the connecting client, to make sure the client is
-authorized to use the requested OS login.
-
-Finally, the client is authorized to create an SSH connection to a node.
-
-![Proxy Connection Established](../../img/proxy_client_connect.svg)
-
-## Teleport CLI tools
-
-Teleport offers two command-line tools. `tsh` is a client tool used by the end
-users, while `tctl` is used for cluster administration.
-
-### `tsh`
-
-`tsh` is similar in nature to OpenSSH `ssh` or `scp`. It has
-subcommands named after them so you can call:
-
-```code
-$ tsh --proxy=p ssh -p 1522 user@host
-$ tsh --proxy=p scp -P example.txt user@host/destination/dir
-```
-
-Unlike `ssh`, `tsh` is very opinionated about authentication: it always uses
-auto-expiring certificates and it always connects to Teleport nodes via a proxy.
-
-When `tsh` logs in, the auto-expiring certificate is stored in `~/.tsh` and is
-valid for 12 hours by default, unless you specify another interval via the
-`--ttl` flag (capped by the server-side configuration).
-
-You can learn more about `tsh` in the [User Manual](../server-access/guides/tsh.mdx).
-
-### `tctl`
-
-`tctl` is used to administer a Teleport cluster. It connects to the Teleport
-Auth Service and allows an administrator to manage Nodes, users, and other
-resources in the cluster.
-
-You can run `tctl` commands either remotely or on the Teleport Auth Service
-host. When run remotely, `tctl` requires that the user authenticate to the
-cluster. When run on the Auth Service host, `tctl` uses the identity of the Auth
-Service itself, and does not require additional authentication.
-
-You can learn more about `tctl` in the [CLI Reference](../setup/reference/cli.mdx#tctl).
+| Certificate Authority (CA) | A Certificate Authority issues x.509 and SSH certificates in the form of public/private key pairs. |
+| Teleport Cluster | A Teleport Cluster manages access to resources - databases, kubernetes clusters, servers, desktops, web apps and clouds.|
+| Teleport Proxy Service | A proxy service allows access to cluster resources from the public network. It is the only service that has to be available from the public network.|
+| Teleport Auth Service | The auth service manages certificate authorities of the cluster. It issues certificates to clients and maintains the audit log.|
+| [Teleport CA](./authentication.mdx) | Teleport's Auth service operates multiple internal certificate authorities. One is used to sign User certificates and the other signs Node certificates. Each certificate is used to prove identity, cluster membership, and manage access.|
+| [Teleport Users](./authorization.mdx) | A Teleport User represents a user or a service that needs access to resources behind Teleport Cluster. Users can be local or external, interactive for users and non-interactive for services. |
+| [Teleport Node](./nodes.mdx) | A Teleport Node is an optional service to replace OpenSSH. |

 ## Next steps

- If you haven't already, read the [Getting Started Guide](../getting-started.mdx) to run a
-  minimal setup of Teleport yourself.
- Set up Teleport for your team with the [Admin Guide](../setup/admin.mdx).
-
 Read the rest of the Architecture Guides:

- [Teleport Users](users.mdx)
+- See how Teleport uses [Certificates](authentication.mdx) for authentication.
+- [Teleport Authorization](authorization.mdx)
 - [Teleport Nodes](nodes.mdx)
- [Teleport Auth](authentication.mdx)
 - [Teleport Proxy](proxy.mdx)
+- Reduce your surface of attack using [TLS routing](./tls-routing.mdx).
+
+Get started with Teleport:
+
+- Read the [Getting Started Guide](../getting-started.mdx) to run a Teleport yourself or
+sign up for [Teleport cloud](https://goteleport.com/signup/).
+- Set up Teleport for your team with the [Admin Guide](../setup/admin.mdx).
+
+
@@ -1,125 +1,73 @@
 ---
 title: Teleport Proxy Service
-description: How Teleport implements SSH and Kubernetes access via a Proxy
-h1: The Proxy Service
+description: Architecture of Teleport's identity-aware proxy service
+h1: Teleport Identity-Aware Proxy Service
 ---

-The proxy is a stateless service that performs three main functions in a
-Teleport cluster:
+Teleport Proxy is a identity aware proxy, with a web UI. Here are Proxy's key features:

-1. It serves as an authentication gateway. It asks for credentials from
-   connecting clients and forwards them to the Auth server via [Auth
-   API](authentication.mdx#auth-api).
-2. It looks up the IP address for a requested Node and then proxies a connection
-   from client to Node.
-3. It serves a Web UI that is used by cluster users to sign up and configure
-   their accounts, explore Nodes in a cluster, log into remote Nodes, join
-   existing SSH sessions or replay recorded sessions.
+- Users can authenticate with a Single-Sign-On or local credentials to access SSH and Windows Desktops via Proxy's web UI.
+- Proxy is identity aware - it makes sure that only authenticated clients can connect to target resources.
+It intercepts traffic for multiple protocols - SSH, Kubernetes, HTTPS, databases.
+It records commands, API calls and queries and streams them to the audit log.
+- Proxy provides networking and connectivity features. Nodes and proxies behind firewalls can connect
+to proxies using reverse tunnels. System administrators can use TLS routing feature to compress all ports for all protocols to one TLS port using TLS routing feature.

-## Connecting to a Node
+![Proxy service](../../img/architecture/proxy.png)

-### Web to SSH Proxy
+<Notice type="tip">
+To create a minimal Teleport cluster, you have run two services:
+Teleport Auth Service and Teleport Proxy Service. For your home lab,
+you can run both services as a one binary and process.
+</Notice>

-In this mode, Teleport Proxy implements WSS - secure web sockets - to proxy a
-client SSH connection:
+## Web UI

-![Teleport Proxy Web](../../img/proxy-web.svg)
+In Web UI, Teleport Proxy implements WSS - secure web sockets - to proxy a
+target resource, for example SSH server or Desktop:

-1. User logs in to Web UI using username and password, and 2nd-factor token if configured (2FA Tokens are not used with SSO providers).
-2. Proxy passes credentials to the Auth Server's API
-3. If Auth Server accepts credentials, it generates a new web session and generates a special ssh keypair associated with this web session. Auth server
-   starts serving [OpenSSH ssh-agent protocol](https://tools.ietf.org/html/draft-miller-ssh-agent-04) to the proxy.
-4. The User obtains an SSH session in the Web UI and can interact with the Node on a web-based terminal. From the Node's perspective, it's a regular SSH
-   client connection that is authenticated using an OpenSSH certificate, so no special logic is needed.
+![Teleport Proxy Web](../../img/architecture/proxy-web-to-resource@1.2x.svg)

 <Admonition
  type="note"
-  title="SSL Encryption"
+  title="TLS Encryption"
 >
-  When using the web UI, the Teleport Proxy terminates SSL traffic and re-encodes data for the SSH client connection.
+  When using the web UI, the Teleport Proxy terminates traffic and re-encodes data for the client connection.
 </Admonition>

-### CLI to SSH Proxy
+## Identity-Aware-Proxy

-**Getting Client Certificates**
+In IAP mode, users initiate the SSO or login flow to sign public keys on their client machines:

-Teleport Proxy implements a special method to let clients get short-lived
-authentication certificates signed by the Certificate Authority (CA) provided by
-the [Auth Service](authentication.mdx#authentication-in-teleport).
-
-![Teleport Proxy SSH](../../img/proxy-ssh-1.svg)
-
-1. A [`tsh` client](../setup/reference/cli.mdx#tsh) generates an OpenSSH key pair. It forwards the generated public key, username, password, and second-factor token to the proxy.
-2. The Proxy Service forwards the request to the Auth Service.
-3. If Auth Service accepts credentials, it generates a new certificate signed by its user CA and sends it back to the Proxy Server. The certificate has a TTL
-   that defaults to 12 hours but can be configured in [`tctl`](../setup/reference/cli.mdx#tctl).
-4. The Proxy Server returns the user certificate to the client and the client stores it in `~/.tsh/keys/example.com`. The certificate is also added to the local SSH agent if one is running.
-
-**Using Client Certificates**
-
-Once the client has obtained a certificate, it can use it to authenticate with
-any Node in the cluster. Users can use the certificate using a standard OpenSSH
-client `ssh` or using `tsh`:
-
-![Teleport Proxy Web](../../img/proxy-ssh-2.svg)
-
-1. A client connects to the Proxy Server and provides target Node's host and port location. There are three lookup mechanisms a proxy uses to find the
-   Node's IP address:
-
-   - Use DNS to resolve the name requested by the client.
-   - Asks the Auth Service if there is a Node registered with this `nodename`.
-   - Asks the Auth Service to find a Node (or Nodes) with a label that matches the requested name.
-
-2. If the Node is located, the Proxy establishes an SSH tunnel to the
-   requested Node and starts forwarding traffic from Node to client.
-
-3. The client uses the established SSH tunnel from Proxy to Node to open a new
-   SSH connection. The client authenticates with the target Node using its
-   client certificate.
+![Teleport Proxy IAP](../../img/architecture/proxy-iap-to-resource@1.2x.svg)

 <Admonition
-  type="tip"
-  title="NOTE"
+  type="note"
+  title="IAP Mode Security"
 >
-  Teleport's proxy command makes it compatible with [SSH jump hosts](https://wiki.gentoo.org/wiki/SSH_jump_host) implemented using OpenSSH's `ProxyCommand`. It also supports OpenSSH's ProxyJump/ssh -J implementation.
+We consider IAP mode more secure than Web UI access, because private keys never leave user's client.
+Client's connection to resource is mutually authenticated. This mode is also less vulnerable
+for web-related attacks, like CSRF or cookie hijacking, because browser is used less.
 </Admonition>

-## Recording Proxy mode
+## Tunnels

-In this mode, the proxy terminates (decrypts) the SSH connection using the
-certificate supplied by the client via SSH agent forwarding and then establishes
-its own SSH connection to the final destination server, effectively becoming an
-authorized "man in the middle". This allows the proxy server to forward SSH
-session data to the auth server to be recorded, as shown below:
+In this mode, resources behind firewall can establish reverse tunnels back to proxies.
+Proxies will forward client's connections to target resources via those tunnels.

-![recording-proxy](../../img/recording-proxy.svg)
+In the example below, Alice connects to kubernetes cluster behind firewall via two tunnels:

-The recording proxy mode, although *less secure*, was added to allow Teleport
-users to enable session recording for OpenSSH's servers running `sshd`, which is
-helpful when gradually transitioning large server fleets to Teleport.
+![Teleport Proxy Tunnel](../../img/architecture/proxy-tunnel@1.2x.svg)

-We consider the "recording proxy mode" to be less secure for two reasons:
-
-1. It grants additional privileges to the Teleport proxy. In the default mode,
-   the proxy stores no secrets and cannot "see" the decrypted data. This makes a
-   proxy less critical to the security of the overall cluster. But if an
-   attacker gains physical access to a proxy Node running in the "recording"
-   mode, they will be able to see the decrypted traffic and client keys stored in the proxy's process memory.
-2. Recording proxy mode requires SSH Agent Forwarding. Agent Forwarding is required because without it, a proxy will not be able to establish the 2nd connection to the destination Node.
-
-However, there are advantages of proxy-based session recording too. When
-sessions are recorded at the Nodes, a root user can add iptables rules to
-prevent sessions logs from reaching the Auth Service. With sessions recorded at
-the proxy, users with root privileges on Nodes have no way of disabling the
-audit.
-
-See the [reference](../setup/reference/audit.mdx#recorded-sessions) to learn how to turn
-on the recording proxy mode. Note that the recording mode is configured on the
-Auth Service.
+<Notice type="tip">
+All modes above are turned on by default in Proxies. No special configuration is necessary, unless you
+want to turn some of those modes off.
+</Notice>

 ## More concepts

+- [TLS Routing](tls-routing.mdx)
 - [Architecture Overview](overview.mdx)
- [Teleport Users](users.mdx)
- [Teleport Auth](authentication.mdx)
+- [Teleport Authentication](authentication.mdx)
+- [Teleport Authorization](authorization.mdx)
 - [Teleport Proxy](proxy.mdx)
@@ -0,0 +1,65 @@
+---
+title: Teleport Trusted Clusters Architecture
+description: Deep dive into design of Teleport Trusted Clusters.
+h1: Trusted Clusters Architecture
+---
+
+## Overview
+
+Teleport can partition compute infrastructure into multiple clusters. A cluster
+is a group of Teleport connected resources. Each cluster
+manages a set of certificate authorities (CAs) for its users and resources.
+
+Trusted Clusters allow the users of one cluster, the **root cluster**, to
+seamlessly SSH into the Nodes of another cluster, the **leaf cluster**, while
+remaining authenticated with only a single Auth Service. The leaf cluster can
+be running behind a firewall without any ingress ports open.
+
+Uses for Trusted Clusters include:
+
+- Managed service providers (MSP) remotely managing the infrastructure of their clients.
+- Device manufacturers remotely maintaining computing appliances deployed on premises.
+- Large cloud software vendors managing multiple data centers.
+
+<Notice type="tip">
+Individual nodes and proxies can create reverse tunnels to proxy services without creating a new cluster.
+You don't need to set up a trusted cluster just to connect a couple of servers, kubernetes clusters or
+databases behind a firewall.
+</Notice>
+
+## Multi-Data-center Clusters
+
+In the example below, there are three independent clusters:
+
+- Cluster `sso.example.com` is a root cluster. This cluster can be used as a single-sign-on entry point
+for your organization. It can have it's own independent resources connected to it, or be used just for audit
+logs collection and single-sign-on.
+- Clusters `us-east-1a` and `us-east-1b` are two independent clusters in different availability zones.
+
+![Trusted clusters](../../img/architecture/trusted-clusters@1.5x.svg)
+
+## Role Mapping
+
+In Teleport, leaf clusters are autonomous - they have their own state, roles and even local users.
+Leaf clusters have autonomy to decide how to map identity of the external users to their local roles.
+We call this process role mapping. Take a look at the flow below to understand how it works:
+
+![Role mapping](../../img/architecture/tc-role-mapping.svg)
+
+<Notice type="tip">
+If this all sounds complicated, but don't worry, you do not need to use trusted clusters unless you have
+large, distributed infrastructure or your organization works with external agencies or contractors who
+need separate access.
+
+In many cases, a single cluster is enough. A single teleport cluster can scale to hundreds of thousands
+of connected resources!
+</Notice>
+
+## Next steps
+
+Read the rest of the Architecture Guides:
+
+- See how Teleport uses [Certificates](authentication.mdx) for authentication.
+- Reduce your surface of attack using [TLS routing](./tls-routing.mdx).
+- Follow our [guide](../setup/admin/trustedclusters.mdx) to set up trusted clusters.
+
@@ -1,132 +0,0 @@
---
-title: Teleport Users
-description: This chapter explains the concept of a Teleport User and how it's different from operating system (OS) users or Kubernetes users.
-h1: Teleport Users
---
-
-## Types of users
-
-Unlike traditional SSH, Teleport introduces the concept of a User Account. A
-User Account is not the same as SSH login. Instead, each Teleport User is
-associated with another account which is used to authenticate the user.
-
-For Open Source edition users, these will be OS users who are administered
-outside of Teleport on each cluster node. For example, there can be a Teleport
-user `joe` who can be permitted to log in as "root" to a specific subset of
-nodes. Another user `juliet` could be permitted to OS users `root` and to
-`nginx`. Teleport does not know the OS Users so it expects both `root` and
-`nginx` to exist on the node.
-
-For Enterprise edition users, these can be stored in an external identity source
-such as Okta, Active Directory, OneLogin, G Suite, or OIDC. Read the
-[Enterprise Guide](../enterprise/introduction.mdx) to learn more.
-
-Teleport supports two types of user accounts: **Local Users** and
-**External Users**.
-
-### Local users
-
-Local users are created and stored in Teleport's own identity storage in the
-Auth Server.
-
-Let's look at this table:
-
-| Teleport User | Allowed OS Logins | Description |
-| - | - | - |
-| joe | joe, root | Teleport user `joe` can log in into member nodes as OS user `joe` or `root`. |
-| juliet | juliet | Teleport user `juliet` can log in into member nodes only as OS user `juliet`. |
-| ross | | If no OS login is specified, it defaults to the same name as the Teleport user, here this is `ross`. |
-
-A cluster administrator must create account entries for every Teleport user with
-[`tctl users add`](../setup/reference/cli.mdx). Every Teleport User must be
-associated with a list of one or more machine-level OS usernames it can
-authenticate as during a login. This list is called "user mappings".
-
-![User Mappings](../../img/user_mappings.svg)
-
-The diagram shows the following mappings. A couple of noteworthy things
-from this example:
-
- Teleport User `sandra` does **not** have access to `grav-02`
-  through Teleport because `ops` is not an OS username on that node.
- Teleport User `joe` has access to all nodes because the OS user `root`
-  is present on all nodes.
-
-| Teleport User | logins | has access to nodes |
-| - | - | - |
-| joe | root, joe | grav-00, grav-01, grav-02 |
-| tara | tara | grav-01, grav-02 |
-| teleport | teleport | grav-00, grav-02 |
-| sandra | ops | grav-00, grav-01 |
-
-Teleport supports second-factor authentication (2FA) when using a local auth
-connector and it is enforced by default.
-
-<Admonition
-  type="tip"
-  title="2FA Support"
->
-  2FA is not supported with SSO providers such as GitHub or Okta. To learn
-  more about SSO configuration check out the [SSO section of the Enterprise
-  Guide](../enterprise/introduction.mdx#sso)
-</Admonition>
-
-There are two types of 2FA supported:
-
- [TOTP - e.g. Google Authenticator](https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm)
- [WebAuthn - e.g. YubiKey](https://webauthn.guide)
-
-`TOTP` is the default. You can use [Google
-Authenticator](https://en.wikipedia.org/wiki/Google_Authenticator) or
-[Authy](https://www.authy.com/) or any other TOTP client.
-
-### External users
-
-{
-  /* TODO: Production topic */
-}
-
-External users are users stored elsewhere within an organization. Examples
-include GitHub, Active Directory (AD), OIDC, or any identity store with an
-OpenID/OAuth2 or SAML endpoint.
-
-<Admonition
-  type="tip"
-  title="Version Warning"
->
-  External user storage is only supported in Teleport
-  Enterprise. Please take a look at the [Teleport
-  Enterprise](../enterprise/introduction.mdx) chapter for more information.
-</Admonition>
-
-#### Multiple identity sources
-
-It is possible to have multiple identity sources configured for a Teleport
-cluster. In this case, an identity source (called a "connector") will have to be
-passed to
-[`tsh --auth=connector_name login`](../setup/reference/cli.mdx#tsh-login).
-
-{
-  /* TODO: Production Configuration */
-}
-
-The local users connector can be specified via [`tsh --auth=local
-login`](../setup/reference/cli.mdx#tsh-login).
-
-## User roles
-
-Unlike traditional SSH, each Teleport user account is assigned a `role`. Having
-roles allows Teleport to implement role-based access control (RBAC), i.e. assign
-users to groups (roles) and restrict each role to a subset of actions on a
-subset of nodes in a cluster.
-
-{
-  /* TODO: Enterprise Topic */
-}
-
-## More concepts
-
- [Architecture Overview](overview.mdx)
- [Teleport Auth](authentication.mdx)
- [Teleport Nodes](nodes.mdx)
- [Teleport Proxy](proxy.mdx)
@@ -16,7 +16,7 @@ whether the Teleport Cloud is ready for strict compliance use-cases.

 ## Managed Teleport Settings

-SSH sessions are recorded [on nodes](../architecture/nodes.mdx#session-recording).
+SSH sessions are recorded [on nodes](../architecture/nodes.mdx).
 Teleport Cloud Proxy does not terminate SSH sessions when using OpenSSH and `tsh` sessions.
 The Cloud Proxy terminates TLS for Application, Database and Kubernetes sessions.

@@ -52,7 +52,7 @@ Let's take a look at the typical flow Database Access users go through to
 connect to a database.

 1. A user logs into the cluster with `tsh login` command and retrieves
-   a client certificate. See [Issuing User Certificates](../architecture/authentication.mdx#issuing-user-certificates)
+   a client certificate. See [Issuing User Certificates](../architecture/authentication.mdx)
   for more details on how it works.
 2. The user picks the database they want to connect to from the list of available
   databases shown in `tsh db ls` command and retrieves a short-lived X.509
@@ -31,7 +31,7 @@ government agencies.
 | [AC-10 Concurrent Session Control]((=fedramp.control_url=)AC-10) | Teleport administrators can define concurrent session limits using Teleport’s RBAC. |
 | [AC-17 Remote Access]((=fedramp.control_url=)AC-17) | Teleport administrators create users with configurable roles that can be used to allow or deny access to system resources. |
 | [AC-20 Use of External Information Systems]((=fedramp.control_url=)AC-20) | Teleport supports connecting multiple independent clusters using a feature called [Trusted Clusters](../setup/admin/trustedclusters.mdx). When allowing access from one cluster to another, roles are mapped according to a pre-defined relationship of the scope of access. |
-| [AU-03 Audit and Accountability]((=fedramp.control_url=)AU-3) – Content of Audit Records and [AU-12 Audit Generation]((=fedramp.control_url=)AU-12) | Teleport contains an [Audit Log](../architecture/authentication.mdx#audit-log) that records cluster-wide events such as: <br/>• Failed login attempts.<br/>• Commands that were executed (SSH “exec” commands).<br/> • Ports that were forwarded. <br/>• File transfers that were initiated. |
+| [AU-03 Audit and Accountability]((=fedramp.control_url=)AU-3) – Content of Audit Records and [AU-12 Audit Generation]((=fedramp.control_url=)AU-12) | Teleport contains an [Audit Log](../setup/reference/audit.mdx) that records cluster-wide events such as: <br/>• Failed login attempts.<br/>• Commands that were executed (SSH “exec” commands).<br/> • Ports that were forwarded. <br/>• File transfers that were initiated. |
 | [AU-10 Non-Repudiation]((=fedramp.control_url=)AU-10) | Teleport audit logging supports both events as well as audit of an entire SSH session. For non-repudiation purposes a full session can be replayed back and viewed. |
 | [CM-08 Information System Component Inventory]((=fedramp.control_url=)CM-8) | Teleport maintains a live list of all nodes within a cluster. This node list can be queried by users (who see a subset they have access to) and administrators any time. |
 | [IA-03 Device Identification and Authentication]((=fedramp.control_url=)IA-3) | Teleport requires valid x509 or SSH certificates issued by a Teleport Certificate Authority (CA) to establish a network connection for device-to-device network connection between Teleport components. |
@@ -159,4 +159,4 @@ is emitted to the Audit Log.
 - Teleport is compiled  with [BoringCrypto](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/3678)
 - User, host and CA certificates (and host keys for recording proxy mode) should only use 2048-bit RSA private keys.

-</ScopedBlock>
+</ScopedBlock>
@@ -65,7 +65,7 @@ Each principle has many “Points of Focus” which will apply differently to di
 | CC6.1 - Identifies and Authenticates Users | Persons, infrastructure, and software are identified and authenticated prior to accessing information assets, whether locally or remotely. | Provide role-based access controls (RBAC) using short-lived certificates and your existing identity management service. Connecting locally or remotely is just as easy. | 
 | CC6.1 - Considers Network Segmentation | Network segmentation permits unrelated portions of the entity&#39;s information system to be isolated from each other. | [Teleport enables beyond corp network segmentation](../setup/admin/trustedclusters.mdx) | [Connect to nodes behind Firewalls or create reverse tunnels to a proxy server](../faq.mdx#can-i-connect-to-nodes-behind-a-firewall) |  |  |  |
 | CC6.1 - Manages Points of Access | Points of access by outside entities and the types of data that flow through the points of access are identified, inventoried, and managed. The types of individuals and systems using each point of access are identified, documented, and managed. | [Label Nodes to inventory and create rules](../setup/admin/labels.mdx) | [Create Labels from AWS Tags](../setup/guides/ec2-tags.mdx) | Teleport maintains a live list of all nodes within a cluster. This node list can be queried by users (who see a subset they have access to) and administrators any time. |  |  |
-| CC6.1 - Restricts Access to Information Assets | Combinations of data classification, separate data structures, port restrictions, access protocol restrictions, user identification, and digital certificates are used to establish access-control rules for information assets. | [Teleport uses Certificates to grant access and create access control rules](../architecture/overview.mdx#4-authenticate-node-certificate) | 
+| CC6.1 - Restricts Access to Information Assets | Combinations of data classification, separate data structures, port restrictions, access protocol restrictions, user identification, and digital certificates are used to establish access-control rules for information assets. | [Teleport uses Certificates to grant access and create access control rules](../architecture/overview.mdx) | 
 | CC6.1 - Manages Identification and Authentication | Identification and authentication requirements are established, documented, and managed for individuals and systems accessing entity information, infrastructure, and software. | Teleport makes setting policies for SSH requirements easy since it works in the cloud and on premise with the same authentication security standards. | 
 | CC6.1 - Manages Credentials for Infrastructure and Software | New internal and external infrastructure and software are registered, authorized, and documented prior to being granted access credentials and implemented on the network or access point. Credentials are removed and access is disabled when access is no longer required or the infrastructure and software are no longer in use. | [Invite nodes to your cluster with short lived tokens](../setup/admin/adding-nodes.mdx) | 
 | CC6.1 - Uses Encryption to Protect Data | The entity uses encryption to supplement other measures used to protect data at rest, when such protections are deemed appropriate based on assessed risk. | Teleport Audit logs can use DynamoDB encryption at rest. | 
@@ -84,7 +84,7 @@ Each principle has many “Points of Focus” which will apply differently to di
 | CC6.7 - Uses Encryption Technologies or Secure Communication Channels to Protect Data | Encryption technologies or secured communication channels are used to protect transmission of data and other communications beyond connectivity access points. | [Teleport has strong encryption including a FedRAMP compliant FIPS mode](./fedramp.mdx#starting-teleport-in-fips-mode) | 
 | CC7.2 - Implements Detection Policies, Procedures, and Tools | Processes are in place to detect changes to software and configuration parameters that may be indicative of unauthorized or malicious software. | [Teleport creates detailed SSH Audit Logs with Metadata](../setup/reference/audit.mdx) | [Use BPF Session Recording to catch malicious program execution](../server-access/guides/bpf-session-recording.mdx) |  |  |  |
 | CC7.2 - Designs Detection Measures | Detection measures are designed to identify anomalies that could result from actual or attempted (1) compromise of physical barriers; (2) unauthorized actions of authorized personnel; (3) use of compromised identification and authentication credentials; (4) unauthorized access from outside the system boundaries; (5) compromise of authorized external parties; and (6) implementation or connection of unauthorized hardware and software. | [Use Enhanced Session Recording to catch malicious program execution, capture TCP connections and log programs accessing files on the system the should not be accessing.](../server-access/guides/bpf-session-recording.mdx) | 
-| CC7.3 - Communicates and Reviews Detected Security Events | Detected security events are communicated to and reviewed by the individuals responsible for the management of the security program and actions are taken, if necessary. | [Use Session recording to replay and review suspicious sessions](../architecture/nodes.mdx#session-recording). | 
+| CC7.3 - Communicates and Reviews Detected Security Events | Detected security events are communicated to and reviewed by the individuals responsible for the management of the security program and actions are taken, if necessary. | [Use Session recording to replay and review suspicious sessions](../architecture/nodes.mdx#ssh-session-recording). | 
 | CC7.3 - Develops and Implements Procedures to Analyze Security Incidents | Procedures are in place to analyze security incidents and determine system impact. | [Analyze detailed logs and replay recorded sessions to determine impact. See exactly what files were accessed during an incident.](../server-access/guides/bpf-session-recording.mdx) | 
 | CC7.4 - Contains Security Incidents | Procedures are in place to contain security incidents that actively threaten entity objectives. | [Use Teleport to quickly revoke access and contain an active incident](../access-controls/guides/locking.mdx)   | [Use Shared Sessions so Multiple On-Call Engineers can collaborate and fight fires together.](../server-access/guides/tsh.mdx#sharing-sessions) |  |  |  |
 | CC7.4 - Ends Threats Posed by Security Incidents | Procedures are in place to mitigate the effects of ongoing security incidents. | [Use Teleport to quickly revoke access and contain an active incident](../access-controls/guides/locking.mdx)   | 
@@ -94,4 +94,4 @@ Each principle has many “Points of Focus” which will apply differently to di
 | CC7.5 - Determines Root Cause of the Event | The root cause of the event is determined. | [Use Session recording and audit logs to find root cause.](../server-access/guides/bpf-session-recording.mdx) | 
 | CC7.5 - Improves Response and Recovery Procedures | Lessons learned are analyzed and the incident-response plan and recovery procedures are improved. | [Replay Session recordings at your &#39;after action review&#39; or postmortem meetings](../server-access/guides/bpf-session-recording.mdx) | 

-</ScopedBlock>
+</ScopedBlock>
@@ -0,0 +1,277 @@
+```yaml
+kind: role
+version: v5
+metadata:
+  name: example
+spec:
+  # options specify connection, in case if user has multiple non-default
+  # conflicting options, teleport chooses the least permissive value.
+  options:
+    # max_session_ttl defines the TTL (time to live) of certificates
+    # issued to the users with this role.
+    max_session_ttl: 8h
+    # forward_agent controls whether SSH agent forwarding is allowed
+    forward_agent: true
+    # port_forwarding controls whether TCP port forwarding is allowed for SSH
+    port_forwarding: true
+    # client_idle_timeout determines if SSH sessions to cluster nodes are
+    # forcefully terminated after no activity from a client (idle client).
+    # it overrides the global cluster setting. examples: "30m", "1h" or "1h30m"
+    client_idle_timeout: never
+    # Determines if the clients will be forcefully disconnected when their
+    # certificates expire in the middle of an active session.
+    # It overrides the global cluster setting.
+    disconnect_expired_cert: no
+    # max_sessions is total number of session channels that can be established
+    # across a single connection. Setting it to 10 matches OpenSSH default behavior.
+    max_sessions: 10
+    # permit_x11_forwarding allows users to use X11 forwarding with openssh
+    # clients and servers through the proxy
+    permit_x11_forwarding: true
+    # require_session_mfa require per-session MFA for any owner of this role
+    require_session_mfa: true
+    # lock sets locking mode for user of this role,
+    # valid values are "strict" or "best_effort"
+    lock: strict
+    # enterprise-only request_access field is either 'always' or 'reason'. If set to always, it instructs
+    # tsh or the web UI clients to always create an access request on login. If it is
+    # set to 'reason', the user will be required to indicate why they are
+    # generating the access request.
+    request_access: reason
+    # the `request_prompt` field can be used to tell the user what should
+    # be supplied in the request reason field.
+    request_prompt: Please provide your ticket ID
+    # enterprise-only max_connections field sets a limit of concurrent sessions within a
+    # cluster. This setting slows down Teleport performance because it has to track
+    # connections cluster-wide.
+    max_connections: 2
+    # Specify whether or not to record the user's desktop sessions.
+    # Desktop session recording is enabled if one or more of the user's
+    # roles has enabled recording. Defaults to true if unspecified.
+    # Desktop sessions will never be recorded if auth_service.session_recording
+    # is set to 'off' in teleport.yaml or if the cluster's session_recording_config
+    # resource has set 'mode: off'.
+    record_sessions:
+      desktop: true
+    # Specify whether clipboard sharing should be allowed with the
+    # remote desktop (requires a supported browser). Defaults to true
+    # if unspecified. If one or more of the user's roles has disabled
+    # the clipboard, then it will be disabled.
+    desktop_clipboard: true
+    # Specify a list of names and associated values to be included in user SSH keys.
+    # The key type can only be "ssh" and the mode can only be "extension".
+    # The name and value fields can be arbitrary strings and the value field
+    # supports variable interpolation.
+    cert_extensions:
+     - type: ssh
+       mode: extension
+       name: login@github.com
+       value: "{{ external.github_login }}"
+
+  # The allow section declares a list of resource/verb combinations that are
+  # allowed for the users of this role. By default, nothing is allowed.
+  allow:
+    # The logins array defines the OS/UNIX logins a user is allowed to use.
+    # both strings and template variables are supported in this field
+    logins: [root, '{{internal.logins}}']
+
+    # Windows logins a user is allowed to use for desktop sessions.
+    windows_desktop_logins: [Administrator, '{{internal.logins}}']
+
+    # node_labels: a user with this role will be allowed to connect to
+    # SSH nodes, which labels match expressions below.
+    node_labels:
+      # literal strings:
+      'env': 'test'
+      # the wildcard ('*') means "any node"
+      '*': '*'
+      # a list of alternative options:
+      'region': ['us-west-1', 'eu-central-1']
+      # regular expressions start with ^ and end with $
+      # Teleport uses golang regexp syntax.
+      # of the list example above can be expressed as:
+      'reg': '^us-west-1|eu-central-1$'
+
+    # kubernetes_groups specifies Kubernetes groups a user with this role will assume.
+    # You can refer to a SAML/OIDC trait via the "external" property bag.
+    # This allows you to specify Kubernetes group membership in an identity manager:
+    kubernetes_groups: ["system:masters", "{{external.trait_name}}"]
+
+    # kubernetes_users is an optional field that specifies kubernetes users
+    # this role can assume.
+    kubernetes_users: ['IAM#{{external.foo}};']
+
+    # kubernetes_labels: a user with this role will be allowed to connect to
+    # k8s clusters, which labels match expressions below.
+    kubernetes_labels:
+      # A user can only access prod environments
+      'env': 'prod'
+      # User can access any region in us-west, e.g us-west-1, us-west-2
+      'region': 'us-west-*'
+      # regular expressions start with ^ and ending with $
+      # Teleport uses golang regexp syntax.
+      'cluster_name': '^us.*\.example\.com$'
+
+    # Functions transform variables.
+    db_users: ['{{email.local(external.email)}}']
+    db_names: ['{{external.db_names}}']
+    db_labels:
+      'env': '{{regexp.replace(external.access["env"], "^(staging)$", "$1")}}'
+
+    # app_labels: a user with this role will be allowed to connect to
+    # applications, which labels match expressions below.
+    app_labels:
+      # A user can only access prod environments
+      'env': 'prod'
+      # User can access any region in us-west, e.g us-west-1, us-west-2
+      'region': 'us-west-*'
+      # Regular expressions start with ^ and end with $.
+      # Teleport uses Go's regular expression syntax:
+      # https://github.com/google/re2/wiki/Syntax
+      # The list example above can be expressed as:
+      # 'region': '^us-west-1|eu-central-1$'
+      'cluster_name': '^us.*\.example\.com$'
+
+    # aws_role_arns allows a user with this role to assume AWS roles when
+    # accessing AWS console using UI or AWS API using CLI
+    aws_role_arns:
+      - 'arn:aws:iam::1234567890:role/ec2-read-only'
+      - 'arn:aws:iam::1234567890:role/ec2-full-access'
+      - 'arn:aws:iam::0987654321:role/example-role'
+
+    # impersonate allows a user with this role to issue certificates on behalf
+    # of other users and roles matching expressions below
+    impersonate:
+      users: ['*']
+      roles: ['jenkins']
+      # where is an optional where condition
+      # further limiting the scope for matching users and roles
+      where: >
+        contains(user.spec.traits["group"], impersonate_role.metadata.labels["group"]) &&
+        contains(user.spec.traits["group"], impersonate_user.metadata.labels["group"])
+
+    # review_requests allows a user holding this role
+    # to approve or deny access requests
+    review_requests:
+      roles: ['dbadmin']
+
+    # request allows a user user request roles matching
+    # expressions below
+    request:
+      # the `roles` list can be a mixture of literals and wildcard matchers
+      roles: ['common', 'dev-*']
+      # thresholds specifies minimum amount of approvers and deniers,
+      # defaults to 1 for both
+      thresholds:
+        # requires at least two qualifying approvers and at least one denier.
+        - approve: 2
+          deny: 1
+
+      # the `claims_to_roles` mapping works the same as it does in
+      # the OIDC connector, with the added benefit that the roles being mapped to
+      # can also be matchers. the below mapping says that users with
+      # the claims `groups: admins` can request any role in the system.
+      claims_to_roles:
+        - claim: 'projects'
+          # matches all group names with a leading 'product-'
+          value: '^product-(.*)$'
+          # generates a role name from the value capture
+          roles: ['$1-admin']
+
+      # Teleport can attach annotations to pending access requests. these
+      # annotations may be literals, or be variable interpolation expressions,
+      # effectively creating a means for propagating selected claims from an
+      # external identity provider to the plugin system.
+      annotations:
+        foo: ['bar']
+        groups: ['{{external.groups}}']
+
+    # Moderated Sessions policy that dictates requirements for starting a session.
+    require_session_join:
+      # Defines the name of the policy. The name serves only as an
+      # identifier in logs and for organisation/categorisation.
+      - name: Auditor oversight
+        # Specifies an RBAC predicate that is used to define
+        # which users count against the required user count of the policy.
+        filter: 'contains(user.roles, "auditor")'
+        # The different session kinds this policy applies to.
+        kinds: ['k8s', 'ssh']
+        # A list of session participant modes that a participant must have
+        # one of in order to count against the policy.
+        modes: ['moderator']
+        # The minimum amount of users that need to match the filter expression
+        # in order to satisfy the policy.
+        count: 1
+
+    # Moderated Sessions policy that dictates the ability to join sessions
+    join_sessions:
+      # Defines the name of the policy. The name serves only as an
+      # identifier in logs and for organisation/categorisation.
+      - name: Auditor oversight
+        # Allows one to join sessions created by other users with these roles
+        roles : ['prod-access']
+        # The different session kinds this policy applies to.
+        kinds: ['k8s', 'ssh']
+        # The list of session participant modes the role may join the session as.
+        modes: ['moderator', 'observer']
+
+    # rules allow a user holding this role to modify other resources
+    # matching expressions below
+    # supported resources:
+    # role               - role resource
+    # user               - user resource
+    #
+    # auth_connector     - any auth connector resource
+    # oidc               - OIDC connector resource
+    # saml               - connector resource
+    # github             - GitHub connector resource
+    #
+    # trusted_cluster    - trusted cluster resource
+    # remote_cluster     - remote cluster resource
+    #
+    # access_request     - access request resource
+    # access_plugin_data - allows modifying access request plugin data
+    #
+    # session            - session playback records
+    # ssh_session        - an active SSH session
+    # event              - structured audit logging event
+    #
+    #
+    # lock                  - lock resource.
+    # network_restrictions  - restrictions for SSH sessions
+    #
+    # auth_server           - auth server resource
+    # proxy                 - proxy resource
+    # node                  - SSH node resource
+    # app_server            - application server resource
+    # db_server             - database proxy server resource
+    # token                 - provisioning token resource
+    # cert_authority        - certificate authority resource
+    #
+    # cluster_name              - resource that contains the cluster name.
+    # cluster_config            - resource that holds cluster level config
+    # cluster_auth_preference   - type of authentication for this cluster
+    # session_recording_config  - resource for session recording config
+    # cluster_audit_config      - resource that holds cluster audit config
+    # cluster_networking_config - resource that holds cluster networking config
+
+    rules:
+      - resources: [role]
+        verbs: [list, create, read, update, delete]
+      - resources: [auth_connector]
+        verbs: [list, create, read, update, delete]
+      - resources: [session]
+        verbs: [list, read]
+      - resources: [trusted_cluster]
+        verbs: [list, create, read, update, delete]
+      - resources: [event]
+        verbs: [list, read]
+      - resources: [user]
+        verbs: [list, create, read, update, delete]
+      - resources: [token]
+        verbs: [list, create, read, update, delete]
+
+  # The deny section uses the identical format as the 'allow' section.
+  # The deny rules always override allow rules.
+  deny: {}
+```
@@ -515,7 +515,7 @@ Set to a number higher than `1` for a high availability mode where multiple Tele
 <Admonition type="warning">
  When using `custom` mode, you **must** use highly-available storage (e.g. etcd, DynamoDB or Firestore) for multiple replicas to be supported.

-  [Information on supported Teleport storage backends](../../../architecture/authentication.mdx#storage-back-ends)
+  [Information on supported Teleport storage backends](../../../setup/reference/backends.mdx)

  Manually configuring NFS-based storage or `ReadWriteMany` volume claims is **NOT** supported for an HA deployment and will result in errors.
 </Admonition>
@@ -8,7 +8,7 @@ videoBanner: 8uO5H-iYw5A
 This guide explains Enhanced Session Recording for SSH with BPF and how to set
 it up in your Teleport cluster.

-Teleport's default [SSH and Kubernetes session recording](../../architecture/nodes.mdx#session-recording)
+Teleport's default [SSH and Kubernetes session recording](../../architecture/nodes.mdx#ssh-session-recording)
 feature captures what is echoed to a terminal.

 This has inherent advantages. For example, because no input is captured, Teleport
@@ -49,7 +49,7 @@ Teleport Enhanced Session Recording mitigates all three concerns by providing ad
 <Notice type="tip">

  Our Standard Session Recording works with older Linux kernels. View
-  [Teleport Nodes](../../architecture/nodes.mdx#session-recording) for more
+  [Teleport Nodes](../../architecture/nodes.mdx#ssh-session-recording) for more
  details.

 </Notice>
@@ -255,6 +255,6 @@ Sessions with Enhanced Session Recording will include the
 ## Next steps

 - Read more about
-  [session recording](../../architecture/nodes.mdx#session-recording).
+  [session recording](../../architecture/nodes.mdx#ssh-session-recording).
 - See all configuration options for Enhanced Session Recording in our
-  [Configuration Reference](../../setup/reference/config.mdx).
+  [Configuration Reference](../../setup/reference/config.mdx).
@@ -5,13 +5,13 @@ h1: Trusted Clusters
 ---

 Teleport can partition compute infrastructure into multiple clusters. A cluster
-is a group of Teleport resources connected to the cluster's Auth Service, which
-acts as a certificate authority (CA) for all users and Nodes in the cluster.
+is a group of Teleport resources connected. Each clustes
+manages a separate certificate authority (CA) for all users and resources.

 Trusted Clusters allow the users of one cluster, the **root cluster**, to
 seamlessly SSH into the Nodes of another cluster, the **leaf cluster**, while
 remaining authenticated with only a single Auth Service. The leaf cluster can
-be running behind a firewall with no TCP ports open to the root cluster.
+be running behind a firewall without any ingress ports open.

 Uses for Trusted Clusters include:

@@ -20,14 +20,18 @@ Uses for Trusted Clusters include:
 - Large cloud software vendors managing multiple data centers using a common proxy.

 Here is an example of an MSP using Trusted Clusters to obtain access to client clusters:
-![MSP Example](../../../img/trusted-clusters/TrustedClusters-MSP.svg)
+![MSP Example](../../../img/trusted-clusters/trusted-clusters@1.5x.svg)

-This setup works as follows: a leaf cluster creates an outbound reverse SSH
-tunnel to the root cluster and keeps the tunnel open. When a user tries to
-connect to a Node inside the leaf cluster using the root's Proxy Service, the
-reverse tunnel is used to establish this connection.
+A leaf cluster always creates an outbound reverse SSH tunnel to the root cluster and keeps the tunnel open.

-![Tunnels](../../../img/tunnel.svg)
+<Notice type="tip">
+Individual nodes and proxies can create reverse tunnels to proxy serivices without creating a new cluster.
+You don't need to set up a trusted cluster just to connect a couple of servers, kubernetes clusters or
+databases behind a firewall. For more information, see [Adding Nodes to the Cluster](./adding-nodes.mdx).
+</Notice>
+
+When a user tries to connect to any resource inside the leaf cluster using the root's proxy, the
+the connection goes through the reverse tunnel.

 This guide will explain how to:

@@ -252,7 +252,7 @@ $ helm upgrade teleport teleport/teleport-cluster \
 <Admonition type="warning">
  When using `custom` mode, you **must** use highly-available storage (e.g. etcd, DynamoDB, or Firestore) for multiple replicas to be supported.

-  [Information on supported Teleport storage backends](../../architecture/authentication.mdx#storage-back-ends)
+  [Information on supported Teleport storage backends](../../setup/reference/backends.mdx)

  Manually configuring NFS-based storage or `ReadWriteMany` volume claims is **NOT** supported for an HA deployment and will result in errors.
 </Admonition>
@@ -274,4 +274,4 @@ $ helm --namespace teleport uninstall teleport
 You can follow our [Getting Started with Teleport guide](../guides/docker.mdx#step-34-creating-a-teleport-user) to finish setting up your
 Teleport cluster.

-</ScopedBlock>
+</ScopedBlock>
@@ -334,4 +334,4 @@ authority is made active.

 ## Further reading

-How the [Teleport Certificate Authority](../../architecture/authentication.mdx#authentication-in-teleport) works.
+How the [Teleport Certificate Authority](../../architecture/authentication.mdx) works.
@@ -37,11 +37,6 @@ to get even more comprehensive audit logs with advanced security.

 </Notice>

-Refer to the
-["Audit Log" section](../../architecture/authentication.mdx#audit-log) in the
-Teleport architecture guide to learn more about how the audit log and Session
-Recording are designed.
-
 ## Events

 <Tabs>
@@ -191,4 +186,4 @@ $ tsh --proxy=proxy play 4c146ec8-eab6-11e6-b1b3-40167e68e931 --format=json
 ```

 </TabItem>
-</Tabs>
+</Tabs>
@@ -185,239 +185,7 @@ spec:
 ### Role

 Interactive and non-interactive users (bots) assume one or many roles.
-Roles govern access to databases, SSH servers, kubernetes clusters, and web apps.

-```yaml
---
-kind: role
-version: v5
-metadata:
-  name: example
-spec:
-  # options specify connection , in case if user has multiple non-default
-  # conflicting options, teleport chooses the least permissive value.
-  options:
-    # max_session_ttl defines the TTL (time to live) of certificates
-    # issued to the users with this role.
-    max_session_ttl: 8h
-    # forward_agent controls whether SSH agent forwarding is allowed
-    forward_agent: true
-    # port_forwarding controls whether TCP port forwarding is allowed for SSH
-    port_forwarding: true
-    # client_idle_timeout determines if SSH sessions to cluster nodes are
-    # forcefully terminated after no activity from a client (idle client).
-    # it overrides the global cluster setting. examples: "30m", "1h" or "1h30m"
-    client_idle_timeout: never
-    # Determines if the clients will be forcefully disconnected when their
-    # certificates expire in the middle of an active session.
-    # It overrides the global cluster setting.
-    disconnect_expired_cert: no
-    # max_sessions is total number of session channels that can be established
-    # across a single connection. Setting it to 10 matches OpenSSH default behavior.
-    max_sessions: 10
-    # permit_x11_forwarding allows users to use X11 forwarding with openssh
-    # clients and servers through the proxy
-    permit_x11_forwarding: true
-    # require_session_mfa require per-session MFA for any owner of this role
-    require_session_mfa: true
-    # lock sets locking mode for user of this role,
-    # valid values are "strict" or "best_effort"
-    lock: strict
-    # enterprise-only request_access field is either 'always' or 'reason'. If set to always, it instructs
-    # tsh or the web UI clients to always create an access request on login. If it is
-    # set to 'reason', the user will be required to indicate why they are
-    # generating the access request.
-    request_access: reason
-    # the `request_prompt` field can be used to tell the user what should
-    # be supplied in the request reason field.
-    request_prompt: Please provide your ticket ID
-    # enterprise-only max_connections field sets a limit of concurrent sessions within a
-    # cluster. This setting slows down Teleport performance because it has to track
-    # connections cluster-wide.
-    max_connections: 2
-    # Specify whether or not to record the user's desktop sessions.
-    # Desktop session recording is enabled if one or more of the user's
-    # roles has enabled recording. Defaults to true if unspecified.
-    # Desktop sessions will never be recorded if auth_service.session_recording
-    # is set to 'off' in teleport.yaml or if the cluster's session_recording_config
-    # resource has set 'mode: off'.
-    record_sessions:
-      desktop: true
-    # Specify whether clipboard sharing should be allowed with the
-    # remote desktop (requires a supported browser). Defaults to true
-    # if unspecified. If one or more of the user's roles has disabled
-    # the clipboard, then it will be disabled.
-    desktop_clipboard: true
+Roles govern access to databases, SSH servers, Kubernetes clusters, web services and applications and Windows Desktops.

-  # The allow section declares a list of resource/verb combinations that are
-  # allowed for the users of this role. By default, nothing is allowed.
-  allow:
-    # The logins array defines the OS/UNIX logins a user is allowed to use.
-    # both strings and template variables are supported in this field
-    logins: [root, '{{internal.logins}}']
-
-    # node_labels: a user with this role will be allowed to connect to
-    # SSH nodes, which labels match expressions below.
-    node_labels:
-      # literal strings:
-      'env': 'test'
-      # the wildcard ('*') means "any node"
-      '*': '*'
-      # a list of alternative options:
-      'region': ['us-west-1', 'eu-central-1']
-      # Teleport uses Go's regular expression syntax, which you can read about here:
-      # https://github.com/google/re2/wiki/Syntax
-      # The list example above can be expressed as:
-      # 'region': '^us-west-1|eu-central-1$'
-
-    # kubernetes_groups specifies Kubernetes groups a user with this role will assume.
-    # You can refer to a SAML/OIDC trait via the "external" property bag.
-    # This allows you to specify Kubernetes group membership in an identity manager:
-    kubernetes_groups: ["system:masters", "{{external.trait_name}}"]
-
-    # kubernetes_users is an optional field that specifies kubernetes users
-    # this role can assume.
-    kubernetes_users: ['IAM#{{external.foo}};']
-
-    # kubernetes_labels: a user with this role will be allowed to connect to
-    # k8s clusters, which labels match expressions below.
-    kubernetes_labels:
-      # A user can only access prod environments
-      'env': 'prod'
-      # User can access any region in us-west, e.g us-west-1, us-west-2
-      'region': 'us-west-*'
-      # regular expressions start with ^ and ending with $
-      # Teleport uses golang regexp syntax.
-      'cluster_name': '^us.*\.example\.com$'
-
-    # Functions transform variables.
-    db_users: ['{{email.local(external.email)}}']
-    db_names: ['{{external.db_names}}']
-    db_labels:
-      'env': '{{regexp.replace(external.access["env"], "^(staging)$", "$1")}}'
-
-    # app_labels: a user with this role will be allowed to connect to
-    # applications, which labels match expressions below.
-    app_labels:
-      # A user can only access prod environments
-      'env': 'prod'
-      # User can access any region in us-west, e.g us-west-1, us-west-2
-      'region': 'us-west-*'
-      # regular expressions start with ^ and ending with $
-      # Teleport uses golang regexp syntax.
-      'cluster_name': '^us.*\.example\.com$'
-
-    # aws_role_arns allows a user with this role to assume AWS roles when
-    # accessing AWS console using UI or AWS API using CLI
-    aws_role_arns:
-      - 'arn:aws:iam::1234567890:role/ec2-read-only'
-      - 'arn:aws:iam::1234567890:role/ec2-full-access'
-      - 'arn:aws:iam::0987654321:role/example-role'
-
-    # impersonate allows a user with this role to issue certificates on behalf
-    # of other users and roles matching expressions below
-    impersonate:
-      users: ['*']
-      roles: ['jenkins']
-      # where is an optional where condition
-      # further limiting the scope for matching users and roles
-      where: >
-        contains(user.spec.traits["group"], impersonate_role.metadata.labels["group"]) &&
-        contains(user.spec.traits["group"], impersonate_user.metadata.labels["group"])
-
-    # review_requests allows a user holding this role
-    # to approve or deny access requests
-    review_requests:
-      roles: ['dbadmin']
-
-    # request allows a user user request roles matching
-    # expressions below
-    request:
-      # the `roles` list can be a mixture of literals and wildcard matchers
-      roles: ['common', 'dev-*']
-      # thresholds specifies minimum amount of approvers and deniers,
-      # defaults to 1 for both
-      thresholds:
-        # requires at least two qualifying approvers and at least one denier.
-        - approve: 2
-          deny: 1
-
-      # the `claims_to_roles` mapping works the same as it does in
-      # the OIDC connector, with the added benefit that the roles being mapped to
-      # can also be matchers. the below mapping says that users with
-      # the claims `groups: admins` can request any role in the system.
-      claims_to_roles:
-        - claim: 'projects'
-          # matches all group names with a leading 'product-'
-          value: '^product-(.*)$'
-          # generates a role name from the value capture
-          roles: ['$1-admin']
-
-      # Teleport can attach annotations to pending access requests. these
-      # annotations may be literals, or be variable interpolation expressions,
-      # effectively creating a means for propagating selected claims from an
-      # external identity provider to the plugin system.
-      annotations:
-        foo: ['bar']
-        groups: ['{{external.groups}}']
-
-    # rules allow a user holding this role to modify other resources
-    # matching expressions below
-    # supported resources:
-    # role               - role resource
-    # user               - user resource
-    #
-    # auth_connector     - any auth connector resource
-    # oidc               - OIDC connector resource
-    # saml               - connector resource
-    # github             - GitHub connector resource
-    #
-    # trusted_cluster    - trusted cluster resource
-    # remote_cluster     - remote cluster resource
-    #
-    # access_request     - access request resource
-    # access_plugin_data - allows modifying access request plugin data
-    #
-    # session            - session playback records
-    # ssh_session        - an active SSH session
-    # event              - structured audit logging event
-    #
-    #
-    # lock                  - lock resource.
-    # network_restrictions  - restrictions for SSH sessions
-    #
-    # auth_server           - auth server resource
-    # proxy                 - proxy resource
-    # node                  - SSH node resource
-    # app_server            - application server resource
-    # db_server             - database proxy server resource
-    # token                 - provisioning token resource
-    # cert_authority        - certificate authority resource
-    #
-    # cluster_name              - resource that contains the cluster name.
-    # cluster_config            - resource that holds cluster level config
-    # cluster_auth_preference   - type of authentication for this cluster
-    # session_recording_config  - resource for session recording config
-    # cluster_audit_config      - resource that holds cluster audit config
-    # cluster_networking_config - resource that holds cluster networking config
-
-    rules:
-      - resources: [role]
-        verbs: [list, create, read, update, delete]
-      - resources: [auth_connector]
-        verbs: [list, create, read, update, delete]
-      - resources: [session]
-        verbs: [list, read]
-      - resources: [trusted_cluster]
-        verbs: [list, create, read, update, delete]
-      - resources: [event]
-        verbs: [list, read]
-      - resources: [user]
-        verbs: [list, create, read, update, delete]
-      - resources: [token]
-        verbs: [list, create, read, update, delete]
-
-  # The deny section uses the identical format as the 'allow' section.
-  # The deny rules always override allow rules.
-  deny: {}
-```
+(!docs/pages/includes/role-spec.mdx!)