![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Getting Started with Teleport Application Access
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
![Getting Started With Teleport Application Access](/docs/_next/image/?url=https%3A%2F%2Fi.ytimg.com%2Fvi%2FcvW4b96aPL0%2Fdefault.jpg&w=256&q=75)
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.
Prerequisites
For this tutorial, verify your environment meets the following requirements:
-
A running Teleport cluster version 16.2.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 andtsh
client tool.Visit Installation for instructions on downloading
tctl
andtsh
.
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.2.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
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 thedomain
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.comIf 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-chartshelm repo updatehelm 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:
-
Install Teleport on your Linux server:
-
Assign edition to one of the following, depending on your Teleport edition:
Edition Value Teleport Enterprise Cloud cloud
Teleport Enterprise (Self-Hosted) enterprise
Teleport Community Edition oss
-
Get the version of Teleport to install. If you have automatic agent updates enabled in your cluster, query the latest Teleport version that is compatible with the updater:
TELEPORT_DOMAIN=example.teleport.comTELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"Otherwise, get the version of your Teleport cluster:
TELEPORT_DOMAIN=example.teleport.comTELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')" -
Install Teleport on your Linux server:
curl https://cdn.teleport.dev/install-v16.2.1.sh | bash -s ${TELEPORT_VERSION} editionThe installation script detects the package manager on your Linux server and uses it to install Teleport binaries. To customize your installation, learn about the Teleport package repositories in the installation guide.
-
-
Create the configuration file for Grafana at
/etc/app_config.yaml
with a command similar to the following:sudo teleport configure \ --output=file \ --proxy=teleport.example.com:443 \ --token=/tmp/token \ --roles=app \ --app-name=grafana \ --app-uri=http://localhost:3000- Set the
--proxy
command-line option to the address for your Teleport cluster (for example,teleport.example.com
ormytenant.teleport.sh
). - Set the
--token
command-line option to the file location on the Application Service host where you saved the invitation token that you generated earlier. - Change the
--app-name
and--app-uri
command-line options if you're configuring access to a different web application.
- Set the
Configure the Teleport Application Service to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Teleport Application Service.
On the host where you will run the Teleport Application Service, enable and start Teleport:
sudo systemctl enable teleportsudo systemctl start teleport
On the host where you will run the Teleport Application Service, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:
sudo teleport install systemd -o /etc/systemd/system/teleport.servicesudo systemctl enable teleportsudo systemctl start teleport
You can check the status of the Teleport Application Service with systemctl status teleport
and view its logs with journalctl -fu teleport
.
Set up the Teleport Helm repository.
Allow Helm to install charts that are hosted in the Teleport Helm repository:
helm repo add teleport https://charts.releases.teleport.dev
Update the cache of charts from the remote repository so you can upgrade to all available releases:
helm repo update
Install the teleport-kube-agent
Helm chart into your Kubernetes cluster to proxy Grafana
with a command similar to the following:
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 16.2.1
- Set
proxyAddr
to the address for your Teleport cluster (for example,teleport.example.com
ormytenant.teleport.sh
). - Set
-authToken
to the invitation token that you previously generated. - Change
apps[0].name
andapps[0].uri
if you're configuring access to a different web application.
Make sure that the Teleport agent pod is running. You should see one
teleport-kube-agent
pod with a single ready container:
kubectl -n teleport-agent get podsNAME 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.