diff --git a/docs/pages/enroll-resources/application-access/guides/connecting-apps.mdx b/docs/pages/enroll-resources/application-access/guides/connecting-apps.mdx
index 509eed746f4c2..536de09778754 100644
--- a/docs/pages/enroll-resources/application-access/guides/connecting-apps.mdx
+++ b/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= --proxy=
-$ 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!)
-
-(!docs/pages/includes/dns-app-access.mdx!)
-
+## 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://.
```
-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 applicatiosn
+ 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".