Skip to content

Commit

Permalink
Edit the "Connecting Apps" guide
Browse files Browse the repository at this point in the history 
Closes #12168

Edit the guide to enrolling web applications with a Teleport cluster to:
- Abide by our conventions for the structure of a how-to guide, e.g., to
  include H2s that indicate step numbers.
- Clarify some missing information from the original guide, such as
  where to start the Application Service as a service, how the
  Application Service and Proxy Service interact, and how labels work.

This change does not attempt to modify the conceptual information at the
end of the guide aside from placing more of it under the "Advanced
options" heading. This is because the product links to these sections in
messages.
  • Loading branch information
@ptgott
ptgott committed Oct 2, 2024
1 parent fe43824 commit de54b0b
Showing 1 changed file with 154 additions and 108 deletions.
262 changes: 154 additions & 108 deletions docs/pages/enroll-resources/application-access/guides/connecting-apps.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 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

Expand All @@ -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".
Expand Down

0 comments on commit de54b0b

Please sign in to comment.