Getting Started with Teleport Application Access

This tutorial demonstrates how to configure secure access to an application through Teleport. The tutorial uses Grafana as a sample application because it's straightforward to install and run in a Docker container or Kubernetes cluster with no additional configuration required. If you want to configure access for a different web application, you can use this tutorial as a general guide for what to do.

At a high level, configuring access for applications involves the following steps:

• Verify your environment meets the prerequisites.
• Verify you can launch the application in a Docker container, Kubernetes cluster, or using another method.
• Generate a short-lived invitation token for the application to join the Teleport cluster.
• Install and configure Teleport on the application host.
• Add a user to verify access to the application.

Prerequisites

For this tutorial, verify your environment meets the following requirements:

• A running Teleport cluster version 17.0.1 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl admin tool and tsh client tool.

  Visit Installation for instructions on downloading tctl and tsh.

• To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example:

  tsh login --proxy=teleport.example.com --user=email@example.com
  tctl status
  Cluster  teleport.example.com
  Version  17.0.1
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.
• A host where you will run the Teleport Application Service.
• A Docker container or Kubernetes cluster to launch Grafana.

Subdomains and applications

Teleport assigns a subdomain to each application you configure for Application Access. For example, if you enroll Grafana as a resource, Teleport assigns the resource to the grafana.teleport.example.com subdomain.

If you host the Teleport cluster on your own network, you should update your DNS configuration to account for application subdomains. You can update DNS in one of two ways:

• Create a single DNS address (A) or canonical name (CNAME) record using wildcard substitution for the subdomain name. For example, create a DNS record with the name *.teleport.example.com.
• Create a separate DNS address (A) or canonical name (CNAME) record for each application subdomain.

Modifying DNS ensures that the certificate authority—for example, Let's Encrypt—can issue a certificate for each subdomain and that clients can verify Teleport hosts regardless of the application they are accessing.

If you use the Teleport cloud platform, no DNS updates are needed because your Teleport cluster automatically provides the subdomains and signed TLS certificates for your applications under your tenant address.

Rights and permissions

This tutorial assumes that you have administrative rights for the Teleport cluster and for the local computer, Docker container, or Kubernetes configuration where the application runs.

The permissions used in this tutorial are intended for demonstration purposes. Before running Teleport in a production environment, you should verify that you're following best practices to avoid security incidents.

Step 1/5. Generate a token

An invitation token is required to authorize a Teleport Application Service instance to join the cluster. Generate a short-lived join token and save it on the host where you will run the Teleport Application Service. For example, you can generate the invitation token by running the following command on a server where the Teleport Auth Service runs:

tctl tokens add \    --type=app \    --app-name=grafana \    --app-uri=http://localhost:3000

Copy the output from this command and save the token in a separate file so it can be passed to the Teleport Application Service.

Step 2/5. Start Grafana

You can start Grafana in a Docker container or Kubernetes cluster by following the appropriate steps.

helm repo add grafana https://grafana.github.io/helm-charts
helm repo update
helm install example-grafana grafana/grafana \    --create-namespace \    --namespace example-grafana

Step 3/5. Install and configure Teleport

sudo systemctl enable teleport
sudo systemctl start teleport

sudo teleport install systemd -o /etc/systemd/system/teleport.service
sudo systemctl enable teleport
sudo systemctl start teleport

helm repo add teleport https://charts.releases.teleport.dev

helm repo update

JOIN_TOKEN=$(cat /tmp/token)
helm install teleport-kube-agent teleport/teleport-kube-agent \  --create-namespace \  --namespace teleport-agent \  --set roles=app \  --set proxyAddr=teleport.example.com:443 \  --set authToken=${JOIN_TOKEN?} \  --set "apps[0].name=grafana" \  --set "apps[0].uri=http://example-grafana.example-grafana.svc.cluster.local" \  --set "apps[0].labels.env=dev" \  --version 17.0.1

kubectl -n teleport-agent get pods
NAME                    READY   STATUS    RESTARTS   AGEteleport-kube-agent-0   1/1     Running   0          32s

Step 4/5. Create a user

Now that you have enrolled the application as a resource protected by Teleport, you can create a user to test access to the application. Teleport has a built-in role called access that allows users to access cluster resources.

To assign to the access role to a new local user named alice, run the following command:

tctl users add --roles=access alice

The command generates an invitation URL for the new user. You can use the URL to choose a password, set up a second factor for authentication, and sign in to the Teleport Web UI.

Step 5/5. Access the application

There are a couple of ways to access the proxied application.

Sign in to the Teleport Web UI using your Teleport cluster address. All available applications are displayed on the Applications tab. Click Launch on the Grafana application tile to access it.

Alternatively, you can call the application directly with its name as the subdomain, for example, https://grafana.teleport.example.com or https://grafana.mytenant.teleport.sh. You are prompted to sign in if you haven't already been authenticated.

Next steps

Learn more about protecting applications with Teleport in the following topics:

• Connecting applications.
• Integrating with JWT tokens.
• Accessing applications with RESTful APIs.
• Setting configuration options AND running CLI commands in the Application Access reference.
• Using the Let's Encrypt ACME protocol.