Securing Infrastructure Access at Scale in Large Enterprises
Dec 12
Virtual
Register Now
Support
LOG IN
Teleport logoTry For Free
Contact SalesTry for Free
Support
LOG IN
Fork me on GitHub

Teleport

Join Services with a Secure Token

Version preview

In this guide, we will show you how to register a Teleport process running one or more services to your cluster by presenting a join token.

In this approach, you declare your intention to register a new Teleport process, and Teleport generates a secure token that the process uses to establish a trust relationship with the Teleport cluster.

Prerequisites

  • 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.

  • A Linux server that you will use to host your Teleport process, e.g., a virtual machine or Docker container with an image based on a Linux distribution.

    In this guide, we will show you how to register a Teleport SSH Service instance. This approach also applies to other Teleport services, like the Proxy Service, Kubernetes Service, Database Service, and other services for accessing resources in your infrastructure.

    The join token method works if a cluster includes a single Proxy Service instance as well as multiple Proxy Service instances behind a load balancer (LB) or a DNS entry with multiple values. If there are multiple Proxy Service instances, a Teleport process joining the cluster establishes a tunnel to every Proxy Service instance.

    If you are using a load balancer, it must use a round-robin or a similar balancing algorithm. Do not use sticky load balancing algorithms (i.e., "session affinity") with Teleport Proxy Service instances.

    If you are using a Docker container, note that this guide assumes that your Linux host has curl and sudo installed.

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.

Step 1/3. Install Teleport

Install Teleport on your Linux host.

Install Teleport on your Linux server:

  1. Assign edition to one of the following, depending on your Teleport edition:

    EditionValue
    Teleport Enterprise Cloudcloud
    Teleport Enterprise (Self-Hosted)enterprise
    Teleport Community Editionoss

  2. 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.com
    TELEPORT_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.com
    TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')"

  3. Install Teleport on your Linux server:

    curl https://cdn.teleport.dev/install-v17.0.1.sh | bash -s ${TELEPORT_VERSION} edition

    The 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.

Step 2/3. Join your Teleport process to the cluster

In this section, we will join your Teleport process to your cluster by:

  • Obtaining a join token
  • Running your Teleport process with the join token

Generate a token

Teleport only allows access to resources in your infrastructure via Teleport processes that that have joined the cluster.

On your local machine, use the tctl tool to generate a new token. In the following example, a new token is created with a TTL of five minutes:

Generate a short-lived invite token for a new Teleport SSH Service instance:
tctl tokens add --ttl=5m --type=node
The invite token: abcd123-insecure-do-not-use-thisThis token will expire in 5 minutes.
Run this on the new node to join the cluster:
> teleport start \   --roles=node \   --token=abcd123-insecure-do-not-use-this \   --ca-pin=sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 \   --auth-server=192.0.2.0:3025
Please note:
  - This invitation token will expire in 5 minutes  - 192.0.2.0:3025 must be reachable from the new node

In this command, we assigned the token the node type, indicating that it will belong to an SSH Service instance.

Copy the token so you can use it later in this guide. You can ignore the rest of the tctl tokens add output.

Here are all the values we support for --type flag when creating a join token:

RoleTeleport Service
appApplication Service
authAuth Service
botMachine ID
dbDatabase Service
discoveryDiscovery Service
kubeKubernetes Service
nodeSSH Service
proxyProxy Service
windowsdesktopWindows Desktop Service

Administrators can generate tokens as they are needed. A Teleport process can use a token multiple times until its time to live (TTL) expires, with the exception of tokens with the bot type, which are used by Machine ID.

To list all of the tokens you have generated, run the following command:

tctl tokens ls
Token                            Type Labels Expiry Time (UTC)-------------------------------- ---- ------ --------------------------abcd123-insecure-do-not-use-this Node        30 Mar 23 18:15 UTC (2m8s)

Use short-lived tokens instead of long-lived static tokens. Static tokens are easier to steal, guess, and leak.

Static tokens are defined ahead of time by an administrator and stored in the Auth Service's config file:

# Config section in `/etc/teleport.yaml` file for the Auth Service
auth_service:
  enabled: true
  tokens:
    # This static token allows new hosts to join the cluster as "proxy" or "node"
    - 'proxy,node:secret-token-value'
    # A token can also be stored in a file. In this example the token for adding
    # new Auth Service instances are stored in /path/to/tokenfile
    - 'auth:/path/to/tokenfile'

Start your Teleport process with the invite token

Execute the following command on the host running your new Teleport process to add it to a cluster. Assign join-token to the token you generated earlier and proxy-address to the host and web port of your Teleport Proxy Service or Teleport Enterprise Cloud tenant (e.g., teleport.example.com:443):

sudo teleport configure \   --roles=node \   --token=join-token \   --proxy=proxy-address \   -o file

For SSH Service instances, you can also run teleport node configure instead of teleport configure. This way, you can exclude the --roles=node flag from the command.

So far, this guide has assumed that you are joining your new Teleport process to your cluster by connecting it to the Proxy Service. (This is the only possibility in Teleport Enterprise Cloud.) Depending on the design of your infrastructure, you may need to connect your new Teleport process directly to the Auth Service.

Only connect Teleport processes directly to the Auth Service if no other join methods are suitable, as we recommend exposing the Auth Service to as few sources of ingress traffic as possible.

The Teleport process joining the cluster must also establish trust with the Auth Service in order to prevent an attacker from hijacking the address of your Auth Service host.

To do this, you supply your new Teleport process with a secure hash value generated by the Auth Service's certificate authority, called a CA pin. This way, an attacker cannot easily forge a private key to trick your Teleport process into communicating with a malicious service.

Obtain a CA pin

On you local machine, retrieve the CA pin of the Auth Service:

tctl status
Cluster      teleport.example.comVersion      12.1.1host CA      never updateduser CA      never updateddb CA        never updatedopenssh CA   never updatedjwt CA       never updatedsaml_idp CA  never updatedCA pin       sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

Copy the CA pin and assign it to the value of ca-pin.

The CA pin becomes invalid if a Teleport administrator performs the CA rotation by executing tctl auth rotate.

Configure your Teleport process with the join token and CA pin

Run the following command to configure your Teleport process instead of the teleport configure command we showed you earlier. Assign auth-service to the host and gRPC port of your Auth Service host, e.g., teleport.example.com:3025.

sudo teleport configure \   --roles=node \   --token=join-token \   --auth-server=auth-service \   -o file

Next, edit the Teleport configuration file, /etc/teleport.yaml, assigning the CA pin (the teleport.ca_pin field) to the one you copied earlier:

sudo sed -i 's|  ca_pin: ""|  ca_pin: "ca-pin"|' /etc/teleport.yaml

Configure your Teleport instance to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed your Teleport instance.

On the host where you will run your Teleport instance, enable and start Teleport:

sudo systemctl enable teleport
sudo systemctl start teleport

On the host where you will run your Teleport instance, 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 your Teleport instance with systemctl status teleport and view its logs with journalctl -fu teleport.

If you followed this guide with a local Docker container, execute the following command within your container to run your new Teleport process in the foreground:

teleport start

As new services come online, they start sending heartbeat requests every few seconds to the Auth Service. This allows users to explore cluster membership and size.

Run the following command on your local machine to see all of the Teleport SSH Service instances in your cluster:

tctl nodes ls
Host          UUID                  Public Address Labels                 Version------------- --------------------- -------------- ---------------------- -------1f58429134c4  6805dda3-779e-493b...                hostname=1f58429134c4  17.0.1

Step 3/3. Revoke an invitation

You can revoke a join token to prevent a Teleport process from using it.

Run the following command on your local machine to create a token for a new Proxy Service:

tctl nodes add --ttl=5m --roles=proxy
The invite token: abcd123-insecure-do-not-use-this.
This token will expire in 5 minutes.
Run this on the new node to join the cluster:
> teleport start \
--roles=proxy \
--token=abcd123-insecure-do-not-use-this \
--ca-pin=sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 \
--auth-server=123.123.123.123:443
Please note:
- This invitation token will expire in 5 minutes
- 123.123.123.123 must be reachable from the new node

Next, run the following command to see a list of outstanding tokens:

tctl tokens ls
Token                            Type  Labels Expiry Time (UTC)-------------------------------- ----- ------ ---------------------------abcd123-insecure-do-not-use-this Node         30 Mar 23 18:20 UTC (36s)efgh456-insecure-do-not-use-this Proxy        30 Mar 23 18:24 UTC (4m39s)
Signup tokens

The output of tctl tokens ls includes tokens used for adding users alongside tokens used for adding Teleport processes to your cluster.

You generated the token with the Node role earlier in this guide to invite a new Teleport process to this cluster. The second token is the one you generated for a Proxy Service instance.

Tokens created via tctl can be deleted (revoked) via the tctl tokens rm command. Copy the second token from the output above and run the following command to delete it, assigning the token to token-to-delete.

tctl tokens rm token-to-delete
Token abcd123-insecure-do-not-use-this has been deleted

Next steps

  • If you have workloads split across different networks or clouds, we recommend setting up trusted clusters. Read how to get started in Configure Trusted Clusters.