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