[v16] Edit the "Connecting Apps" guide

docs/pages/enroll-resources/application-access/guides/connecting-apps.mdx

@@ -2,78 +2,180 @@
 title: Web Application Access
 description: In this getting started guide, learn how to connect an application to your Teleport cluster by running the Teleport Application Service.
 ---
-## Prerequisites
 
-(!docs/pages/includes/edition-prereqs-tabs.mdx!)
+This guide shows you how to enroll a web application with your Teleport cluster
+in order to set up role-based access controls, audit logging, and other Teleport
+capabilities.
 
-- (!docs/pages/includes/tctl.mdx!)
-- Web application to connect to such as Grafana.
-- Host where you will run the Teleport Application Service.
+## How it works
 
-### Generate a token
+To enroll a web application with your Teleport cluster, you deploy the Teleport
+Application Service, which uses a join token to establish trust with the
+Teleport Auth Service. Users visit Teleport-protected web applications through
+the Teleport Web UI. The Teleport Proxy Service routes browser traffic to the
+Teleport Application Service, which forwards HTTP requests to and from target
+applications. 
 
-A join token is required to authorize a Teleport Application Service to
-join the cluster. Generate a short-lived join token and save it for example
-in `/tmp/token`:
-
-```code
-# Log in to your cluster with tsh so you can use tctl from your local machine.
-$ tsh login --user=<Var name="myuser"/> --proxy=<Var name="teleport.example.com"/>
-$ tctl tokens add \
-    --type=app \
-    --app-name=grafana \
-    --app-uri=http://localhost:3000
-```
+## Prerequisites
 
-### TLS requirements
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
 
-TLS is required to secure the Teleport Access Platform and any connected
-applications. When setting up Teleport, the minimum requirement is a certificate
-for the Teleport Proxy Service and a wildcard certificate for its sub-domain. This is where
-everyone will log into Teleport.
+- A web application that you want to protect with Teleport. The web application
+  should be running in a private network. In this guide, we assume that the web
+  application is available on `app.example.com:3000`.
+- A Linux server where you will run the Teleport Application Service. Your
+  network must enable the server to connect to your web application.
+- (!docs/pages/includes/tctl.mdx!)
 
-<Admonition type="tip" title="Application Access and DNS">
-(!docs/pages/includes/dns-app-access.mdx!)
-</Admonition>
+## Step 1/3. Deploy the Teleport Application Service
 
-In this example:
+In this step, you will configure the Teleport Application Service to proxy a
+target application, then deploy a Teleport Agent to run the service.
 
-- `teleport.example.com` hosts the Teleport Auth Service and the Teleport Proxy Service that are the
-  that form the core cluster services of the Teleport Access Platform.
-- `*.teleport.example.com` hosts all of the applications, for example, `grafana.teleport.example.com`.
+### Generate a token
 
-(!docs/pages/includes/tls-certificate-setup.mdx!)
+A join token is required to authorize a Teleport Application Service to
+join the cluster. 
 
-### Create a user
+1. Generate a short-lived join token. Make sure to change `app-name` to the name
+   of your application and `app-uri` to the application's domain name and port:
 
-A Teleport user needs their role's permission to access an application. Teleport
-comes with a built-in `access` role that grants access to all apps:
+   ```code
+   $ tctl tokens add \
+       --type=app \
+       --app-name=my-app \
+       --app-uri=app.example.com:3000 \
+       --ttl=1h
+   ```
 
-```code
-$ tctl users add --roles=access appuser
-```
+   This command creates a join token with a TTL of 1 hour.
 
-## Start the Application Service with CLI flags
+1. Copy the token and save it in `/tmp/token` on the Linux server that will run
+   the Teleport Application Service.
 
-Install Teleport:
+### Install the Teleport Application Service
 
-(!docs/pages/includes/install-linux.mdx!)
+Follow the instructions below on the host where you will install the Teleport
+Application Service:
 
-You can start the Teleport Application Service with a single CLI command:
+(!docs/pages/includes/install-linux.mdx!)
 
-```code
-$ sudo teleport start \
-    --roles=app \
-    --token=/tmp/token \
-    --auth-server=teleport.example.com:3080 \
-    --app-name="grafana" \
-    --app-uri="http://localhost:3000" \
-    --labels=env=dev
+### Configure the Teleport Application Service
+
+1. On the host where you will run the Teleport Application Service, create a
+   file at `/etc/teleport.yaml` with the following content:
+
+   ```yaml
+   version: v3
+   teleport:
+     join_params:
+       token_name: "/tmp/token"
+       method: token
+     proxy_server: "teleport.example.com:443"
+   auth_service:
+     enabled: off
+   proxy_service:
+     enabled: off
+   ssh_service:
+     enabled: off
+   app_service:
+     enabled: true
+     apps:
+     - name: my-app
+       uri: "app.example.com:3000"
+       labels:
+         env: "demo"
+   ```
+
+1. Edit `/etc/teleport.yaml` to replace `teleport.example.com:443` with the host
+   and port of your Teleport Proxy Service or Teleport Enterprise (Cloud)
+   account, e.g., `example.teleport.sh:443`.
+
+1. Change `app.example.com:3000` to match the host and port of your own web
+   application.
+
+   The `app_service` field configures the Teleport Application Service. Each
+   item within `app_service.apps` is an application configuration. The `labels`
+   field assigns a label to each application. You can use Teleport labels to
+   allow and deny users access to resources, as we will demonstrate later in
+   this guide.
+
+### Run the Teleport Application Service
+
+(!docs/pages/includes/start-teleport.mdx service="the Teleport Application Service"!)
+
+## Step 2/3. [Optional] Configure TLS and DNS for your web applications
+
+Once the Teleport Application Service is proxying traffic to your web
+application, the Teleport Proxy Service makes the application available at the
+following URL:
+
+```text
+https://<APPLICATION_NAME>.<TELEPORT_DOMAIN>
 ```
 
-Note that the `--auth-server` flag must point to the Teleport cluster's proxy
-endpoint because the Application Service always connects back to the cluster over
-a reverse tunnel.
+For example, if your Teleport domain name is `teleport.example.com`, the
+application named `my-app` would be available at
+`https://my-app.teleport.example.com`. The Proxy Service presents a TLS
+certificate for this domain name that browsers can verify against a certificate
+authority.
+
+If you are using Teleport Enterprise (Cloud), DNS records and TLS certificates
+for this domain name are provisioned automatically. If you are self-hosting
+Teleport, you must configure these yourself:
+
+1. Create either:
+   - A DNS A record that associates a wildcard subdomain of your Teleport Proxy
+     Service domain, e.g., `*.teleport.example.com`, with the IP address of the
+     Teleport Proxy Service.
+   - A DNS CNAME record that associates a wildcard subdomain of your Proxy
+     Service domain, e.g., `*.teleport.example.com`, with the domain name of the
+     Teleport Proxy Service.
+
+1. Ensure that your system provisionings TLS certificates for
+   Teleport-registered applications. The method to use depends on how you
+   originally set up TLS for your self-hosted Teleport deployment, and is
+   outside the scope of this guide. 
+
+   In general, the same system that provisions TLS certificates signed for the
+   web address of the Proxy Service (e.g., `teleport.example.com`) must also
+   provision certificates for the wildcard address used for applications (e.g.,
+   `*.teleport.example.com`).
+
+## Step 3/3. Configure RBAC and access the application
+
+1. Create a role called `demo-app-access` that allows access to applications
+   with the `env:demo` label that you assigned to the application that you
+   enrolled earlier:
+
+   ```yaml
+   kind: role
+   version: v7
+   metadata:
+     name: demo-app-access
+   spec:
+     allow:
+       app_labels:
+         env: "demo"
+   ```
+
+1. Create a user called `appuser` with the `demo-app-access` role:
+
+   ```code
+   $ tctl users add --roles=demo-app-access appuser
+   ```
+
+   When `appuser` attempts to access the application you enrolled earlier
+   through the Teleport Web UI, the the Teleport Proxy Service forwards the
+   request with a Teleport-signed JSON web token to the Teleport Application
+   Service. The Application Service checks the user's roles and, since the value
+   of `allow.app_labels` matches one of the labels assigned to the application,
+   the Application Service forwards the request to the application.
+
+1. Sign in to the Teleport Web UI as `appuser`. You should see the option to
+   visit the web application that you enrolled.
+
+## Advanced options
 
 ### Application name
 
@@ -90,62 +192,6 @@ e.g. `grafana.teleport.example.com`. You can also override `public_addr` e.g
 `grafana.acme.com` if you configure the appropriate DNS entry to point to the
 Teleport proxy server.
 
-## Start the Teleport Application Service with a config file
-
-Example `teleport.yaml` configuration:
-
-```yaml
-version: v3
-teleport:
-  # Data directory for the Application Proxy service. If running on the same
-  # node as Auth/Proxy service, make sure to use different data directories.
-  data_dir: /var/lib/teleport-app
-  # Instructs the service to load the auth token from the specified file
-  # during initial registration with the cluster.
-  auth_token: /tmp/token
-  # Proxy address to connect to. Note that it has to be the proxy address
-  # because the app service always connects to the cluster over a reverse
-  # tunnel.
-  proxy_server: teleport.example.com:3080
-app_service:
-    enabled: yes
-    # Teleport provides a small debug app called "dumper" that can be used
-    # to make sure application access is working correctly. It outputs JWTs,
-    #  so it can be useful when extending your application.
-    debug_app: true
-    # This section contains definitions of all applications proxied by this
-    # service. It can contain multiple items.
-    apps:
-      # Name of the application. Used for identification purposes.
-    - name: "grafana"
-      # URI and port the application is available at.
-      uri: "http://localhost:3000"
-      # Optional application public address to override.
-      public_addr: "grafana.teleport.example.com"
-      # Optional static labels to assign to the app. Used in RBAC.
-      labels:
-        env: "prod"
-      # Optional dynamic labels to assign to the app. Used in RBAC.
-      commands:
-      - name: "os"
-        command: ["/usr/bin/uname"]
-        period: "5s"
-auth_service:
-  enabled: "no"
-ssh_service:
-  enabled: "no"
-proxy_service:
-  enabled: "no"
-```
-
-Start the Application Service:
-
-```code
-$ sudo teleport start --config=/path/to/teleport.yaml
-```
-
-## Advanced options
-
 ### Running the dumper application
 
 For testing and debugging purposes, we provide a built-in debug app called "dumper".

docs/pages/enroll-resources/application-access/guides/vnet.mdx

@@ -152,7 +152,7 @@ app is [a TCP app](tcp.mdx), so they can be made available over VNet as well. Yo
   application will not be accessible in browsers over plain HTTP, even with VNet running. It's
   possible to work around this by setting a custom `public_addr` as explained above in this guide.
 - If the application needs to be accessible over HTTPS, it must handle TLS connections and return [a valid
-  cert](connecting-apps.mdx#tls-requirements) for the domain it is served on.
+  cert](connecting-apps.mdx#step-23-optional-configure-tls-and-dns-for-your-web-applications) for the domain it is served on.
 - [JWT Token](../jwt/introduction.mdx), [redirect](connecting-apps.mdx#rewrite-redirect) and
   [header rewrites](connecting-apps.mdx#headers-passthrough) are not available for TCP apps.
 - Teleport records the start and the end of a session for TCP apps in the audit log, but [session