Teleport

Getting Started with Teleport Application Access

Available for:
OpenSource
Team
Cloud
Enterprise

Getting Started With Teleport Application Access

Length: 11:27

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.

The following diagram illustrates protecting access to Grafana using Teleport:

Prerequisites

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

A running Teleport cluster. For details on how to set this up, see the Getting Started guide.
The tctl admin tool and tsh client tool version >= 14.2.0.

See Installation for details.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport v14.2.0 git:api/14.0.0-gd1e081e go1.21
  tsh version
Teleport v14.2.0 go1.21
Proxy version: 14.2.0Proxy: teleport.example.com

A Teleport Team account. If you don't have an account, sign up to begin your free trial.
The Enterprise tctl admin tool and tsh client tool, version >= 14.1.3.

You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21
  tsh version
Teleport v14.1.3 go1.21
Proxy version: 14.1.3Proxy: teleport.example.com

A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
The Enterprise tctl admin tool and tsh client tool version >= 14.2.0.

You can download these tools by visiting your Teleport account workspace.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v14.2.0 git:api/14.0.0-gd1e081e go1.21
  tsh version
Teleport v14.2.0 go1.21
Proxy version: 14.2.0Proxy: teleport.example.com

A Teleport Enterprise Cloud account. If you don't have an account, sign up to begin a free trial of Teleport Team and upgrade to Teleport Enterprise Cloud.
The Enterprise tctl admin tool and tsh client tool version >= 14.1.3.

You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21
  tsh version
Teleport v14.1.3 go1.21
Proxy version: 14.1.3Proxy: teleport.example.com

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. tctl is supported on macOS and Linux machines. For example:
```
tsh login --proxy=teleport.example.com --user=[email protected]
tctl status
Cluster  teleport.example.com
Version  14.2.0
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.

When running Teleport in production, you should adhere to the following best practices to avoid security incidents:

Avoid using sudo in production environments unless it's necessary.
Create new, non-root, users and use test instances for experimenting with Teleport.
Run Teleport's services as a non-root user unless required. Only the SSH Service requires root access. Note that you will need root permissions (or the CAP_NET_BIND_SERVICE capability) to make Teleport listen on a port numbered < 1024 (e.g. 443).
Follow the principle of least privilege. Don't give users permissive roles when more a restrictive role will do. For example, don't assign users the built-in access,editor roles, which give them permissions to access and edit all cluster resources. Instead, define roles with the minimum required permissions for each user and configure access requests to provide temporary elevated permissions.
When you enroll Teleport resources—for example, new databases or applications—you should save the invitation token to a file. If you enter the token directly on the command line, a malicious user could view it by running the history command on a compromised system.

You should note that these practices aren't necessarily reflected in the examples used in documentation. Examples in the documentation are primarily intended for demonstration and for development environments.

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.

To start Grafana in a Docker container:

Open a terminal on a computer where Docker is installed.

Start Grafana by running the following command:

docker run --detach --name grafana --publish 3000:3000 grafana/grafana

Edit the /etc/grafana/grafana.ini file in the container to use the address for your Teleport cluster.

Under the [server] section, uncomment the domain key and set the value to the address for your Teleport cluster. For example:
```
The public facing domain name used to access grafana from a browser
domain = teleport.example.com
```
If you can't edit this file in the container, you can use the sed command to edit the file. For example:
```
docker exec --user 0 grafana sed -i \  's/;domain = localhost/domain = teleport.example.com/g' \  /etc/grafana/grafana.ini
```

If you install Grafana with the following helm instructions, it is available at http://example-grafana.example-grafana.svc.cluster.local in the Kubernetes cluster.

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

Select a Teleport edition, then follow the Installation instructions for your environment.

To install on Linux:

Select an edition, then follow the instructions for that edition to install Teleport.

Teleport Edition

curl https://goteleport.com/static/install.sh | bash -s 14.2.0

Add the Teleport repository to your repository list:

Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc
Source variables about OS version
source /etc/os-release
Add the Teleport APT repository for cloud.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport-ent-updater

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"
sudo yum install teleport-ent-updater
Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

Install teleport
sudo dnf install teleport-ent-updater

Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

Source variables about OS version
source /etc/os-release
Add the Teleport Zypper repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")

Install teleport
sudo zypper install teleport-ent-updater

OS repository channels

The following channels are available for APT, YUM, and Zypper repos. They may be used in place of stable/v14 anywhere in the Teleport documentation.

Channel name	Description
`stable/<major>`	Receives releases for the specified major release line, i.e. `v14`
`stable/cloud`	Rolling channel that receives releases compatible with current Cloud version
`stable/rolling`	Rolling channel that receives all published Teleport releases

Before installing a teleport binary with a version besides v14, read our compatibility rules to ensure that the binary is compatible with Teleport Cloud.

When running multiple teleport binaries within a cluster, the following rules apply:

Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
Servers support clients that are 1 major version behind, but do not support clients that are on a newer major version. For example, an 8.x.x Proxy Service is compatible with 7.x.x resource services and 7.x.x tsh, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first.
Proxy Services and resource services do not support Auth Services that are on an older major version, and will fail to connect to older Auth Services by default. This behavior can be overridden by passing --skip-version-check when starting Proxy Services and resource services.

Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc
Source variables about OS version
source /etc/os-release
Add the Teleport APT repository for v14. You'll need to update this
file for each major release of Teleport.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v14" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport-ent