Transforming Privileged Access: A Dialogue on Secretless, Zero Trust Architecture
Watch the Replay
Teleport logoTry For Free
Fork me on GitHub

Teleport

Getting Started with Teleport Application Access

  • Available for:
  • OpenSource
  • Enterprise
  • Cloud
Getting Started With Teleport Application Access

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. For details on how to set this up, see the Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 15.1.10.

    See Installation for details.

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

tctl version

Teleport v15.1.10 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v15.1.10 go1.21

Proxy version: 15.1.10Proxy: 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 >= 15.1.10.

    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 v15.1.10 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v15.1.10 go1.21

Proxy version: 15.1.10Proxy: teleport.example.com
  • A Teleport Enterprise Cloud account. If you don't have an account, sign up to begin a free trial.

  • The Enterprise tctl admin tool and tsh client tool version >= 15.1.9.

    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 v15.1.9 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v15.1.9 go1.21

Proxy version: 15.1.9Proxy: 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 15.1.10

    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:

  1. Open a terminal on a computer where Docker is installed.

  2. Start Grafana by running the following command:

    docker run --detach --name grafana --publish 3000:3000 grafana/grafana
  3. 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:

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

    Teleport Edition

    The following command updates the repository for the package manager on the local operating system and installs the provided Teleport version:

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

    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 v15. 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/v15" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

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

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    sudo apt-get install teleport-ent-fips

    Source variables about OS version

    source /etc/os-release

    Add the Teleport YUM repository for v15. You'll need to update this

    file for each major release of Teleport.

    First, get the major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
    sudo yum install -y yum-utils
    sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v15/teleport.repo")"
    sudo yum install teleport-ent

    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

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    sudo yum install teleport-ent-fips

    Source variables about OS version

    source /etc/os-release

    Add the Teleport Zypper repository for v15. You'll need to update this

    file for each major release of Teleport.

    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")
    sudo yum install teleport-ent

    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

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    sudo yum install teleport-ent-fips

    Source variables about OS version

    source /etc/os-release

    Add the Teleport YUM repository for v15. You'll need to update this

    file for each major release of Teleport.

    First, get the 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/v15/teleport.repo")"

    Install teleport

    sudo dnf install teleport-ent

    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

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    sudo dnf install teleport-ent-fips

    Source variables about OS version

    source /etc/os-release

    Add the Teleport Zypper repository.

    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/v15/teleport-zypper.repo")

    Install teleport

    sudo zypper install teleport-ent

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    sudo zypper install teleport-ent-fips

    In the example commands below, update $SYSTEM_ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

    curl https://cdn.teleport.dev/teleport-ent-v15.1.10-linux-$SYSTEM_ARCH-bin.tar.gz.sha256

    <checksum> <filename>

    curl -O https://cdn.teleport.dev/teleport-ent-v15.1.10-linux-$SYSTEM_ARCH-bin.tar.gz
    shasum -a 256 teleport-ent-v15.1.10-linux-$SYSTEM_ARCH-bin.tar.gz

    Verify that the checksums match

    tar -xvf teleport-ent-v15.1.10-linux-$SYSTEM_ARCH-bin.tar.gz
    cd teleport-ent
    sudo ./install

    For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:

    curl https://cdn.teleport.dev/teleport-ent-v15.1.10-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256

    <checksum> <filename>

    curl -O https://cdn.teleport.dev/teleport-ent-v15.1.10-linux-$SYSTEM_ARCH-fips-bin.tar.gz
    shasum -a 256 teleport-ent-v15.1.10-linux-$SYSTEM_ARCH-fips-bin.tar.gz

    Verify that the checksums match

    tar -xvf teleport-ent-v15.1.10-linux-$SYSTEM_ARCH-fips-bin.tar.gz
    cd teleport-ent
    sudo ./install

    OS repository channels

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

    Channel nameDescription
    stable/<major>Receives releases for the specified major release line, i.e. v15
    stable/cloudRolling channel that receives releases compatible with current Cloud version
    stable/rollingRolling channel that receives all published Teleport releases

    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

    Provide your Teleport domain to query the latest compatible Teleport version

    export TELEPORT_DOMAIN=example.teleport.com
    export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Update the repo and install Teleport and the Teleport updater

    sudo apt-get update
    sudo apt-get install "teleport-ent=$TELEPORT_VERSION" 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 install -y yum-utils
    sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

    Provide your Teleport domain to query the latest compatible Teleport version

    export TELEPORT_DOMAIN=example.teleport.com
    export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Install Teleport and the Teleport updater

    sudo yum install "teleport-ent-$TELEPORT_VERSION" 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")"

    Provide your Teleport domain to query the latest compatible Teleport version

    export TELEPORT_DOMAIN=example.teleport.com
    export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Install Teleport and the Teleport updater

    sudo dnf install "teleport-ent-$TELEPORT_VERSION" 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")

    Provide your Teleport domain to query the latest compatible Teleport version

    export TELEPORT_DOMAIN=example.teleport.com
    export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Install Teleport and the Teleport updater

    sudo zypper install "teleport-ent-$TELEPORT_VERSION" 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/v15 anywhere in the Teleport documentation.

    Channel nameDescription
    stable/<major>Receives releases for the specified major release line, i.e. v15
    stable/cloudRolling channel that receives releases compatible with current Cloud version
    stable/rollingRolling channel that receives all published Teleport releases

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

    Teleport uses Semantic Versioning. Version numbers include a major version, minor version, and patch version, separated by dots. 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 one major version behind, but do not support clients that are on a newer major version. For example, an 8.x.x Proxy Service instance is compatible with 7.x.x agents and 7.x.x tsh, but we don't guarantee that a 9.x.x agent will work with an 8.x.x Proxy Service instance. 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 Service instances and agents do not support Auth Service instances that are on an older major version, and will fail to connect to older Auth Service instances by default. You can override version checks by passing --skip-version-check when starting agents and Proxy Service instances.
  2. 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 or mytenant.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.

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 teleport
sudo 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.service
sudo systemctl enable teleport
sudo 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 "labels.env=dev" \ --version 15.1.10
  • Set proxyAddr to the address for your Teleport cluster (for example, teleport.example.com or mytenant.teleport.sh).
  • Set -authToken to the invitation token that you previously generated.
  • Change apps[0].name and apps[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 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: