Fork me on GitHub

Teleport

Teleport Enterprise Quick Start

Improve

This guide shows you how to get up and running with Teleport Enterprise.

There are three types of services Teleport can run:

  • Auth Service stores user accounts and provides authentication and authorization for every resource service and every user in a cluster.
  • Proxy Service routes client connection requests to the appropriate agent and serves a Web UI that can also be used to access resources.
  • Agents provide access to resources including SSH servers, Kubernetes clusters, web applications and databases.

In this guide, we will highlight the Teleport SSH Service. The SSH Service is similar to the sshd daemon you may be familiar with. SSH Service instances are called Teleport Nodes. When a Teleport Node receives a connection request, the request is authenticated through the cluster's Auth Service.

The teleport daemon runs all three of these services by default.

This guide will run a Teleport cluster consisting of the Auth Service, Proxy Service, and SSH Service, and interact with the cluster using Teleport's client-side tools:

ToolDescription
tctlCluster administration tool used to invite Nodes to a cluster and manage user accounts.
tshAllows users to authenticate and access resources via their local machine. tsh's SSH functionality is similar in principle to OpenSSH's ssh. Users can log in to remote Nodes, list and search for Nodes in a cluster, securely upload/download files, etc.
browserYou can use your web browser to log in to any Teleport Node by opening https://<proxy-host>:3080.

Prerequisites

You will need to have access to the customer portal to download the software. You will also need three computers: two servers and one client (probably a laptop) to complete this tutorial. Let's assume the servers have the following DNS names and IPs:

Server NameIP AddressPurpose
"auth.example.com"10.1.1.10This server will be used to run all three Teleport services: auth, proxy and ssh.
"node.example.com"10.1.1.11This server will only run the SSH service.

This Quick Start Guide assumes that both servers are running a systemd-based Linux distribution such as Debian, Ubuntu or a RHEL derivative. The node.example.com must be able to connect to the auth.example.com 3025 port and the auth.example.com must be able to connect to the 3022 port on node.example.com.

Optional: Quickstart using Docker

The instructions below describe how to install Teleport Enterprise directly onto your test system. You can also run Teleport Enterprise using Docker if you don't want to install Teleport Enterprise binaries straight away.

Installing

To start using Teleport Enterprise, you will need to Download the binaries and the license file from the customer portal. After downloading the binary tarball, run:

tar -xzf teleport-ent-v10.1.2-linux-amd64-bin.tar.gz
cd teleport-ent
  • Copy teleport and tctl binaries to a bin directory (we suggest /usr/local/bin) on the auth server.
  • Copy teleport binary to a bin directory on the node server.
  • Copy tsh binary to a bin directory on the client computer.

License File

The Teleport license file contains a X.509 certificate and the corresponding private key in PEM format.

Download the license file from the customer portal and save it as /var/lib/teleport/license.pem on the auth server.

Systemd Unit File

Download the systemd unit file for Teleport from the examples directory on GitHub and save it as /etc/systemd/system/teleport.service on both servers.

run this on both servers:

sudo systemctl daemon-reload
sudo systemctl enable teleport

Configuration File

Save the following configuration file as /etc/teleport.yaml on the auth.example.com:

teleport:
  nodename: auth.example.com
  auth_token: dogs-are-much-nicer-than-cats
  auth_servers: [ "localhost:3025" ]

proxy_service:
  # enable the proxy service
  enabled: true

auth_service:
  # enable the auth service:
  enabled: true

  tokens:
  # this static token is used for other nodes to join this Teleport cluster
  - proxy,node:dogs-are-much-nicer-than-cats
  # this token is used to establish trust with other Teleport clusters
  - trusted_cluster:trains-are-superior-to-cars

  # by default, local authentication will be used with 2FA
  authentication:
      second_factor: otp

  # SSH is also enabled on this node:
ssh_service:
  enabled: "yes"

Start Teleport on auth.example.com

Start the Teleport service and confirm the service has started. After it has started you can get the Certificate Authority (CA) pin that has been generated.

sudo systemctl start teleport

confirm Teleport started

sudo systemctl status teleport

after successful start retrieve the CA pin for using in the node

sudo tctl status

Cluster teleport

Version 10.0

Host CA never updated

User CA never updated

Jwt CA never updated

CA pin sha256:58b1c5cb8885d84ce08f3e3a47acb33d49841f12dd7648c0c1dd31bd501628

Copy the CA pin from the output of tctl status. On node.example.com save the following configuration file as /etc/teleport.yaml and use the CA pin you copied as the value of ca_pin.

teleport:
  nodename: node.example.com
  auth_token: dogs-are-much-nicer-than-cats
  # you can also use auth server's IP, i.e. "10.1.1.10:3025"
  auth_servers: [ "auth.example.com:3025" ]
  # Set the ca_pin value so it can verify the Teleport server
  ca_pin: sha256:58b1c5cb8885d84ce08f3e...

  # enable ssh service and disable auth and proxy:
ssh_service:
  enabled: true
auth_service:
  enabled: false
proxy_service:
  enabled: false

Start Node service

run this on node server:

sudo systemctl start teleport

Confirm node has started successfully and connected

sudo systemctl status teleport

Teleport Status and Networking

You can review the logs of the Teleport service with journalctl -fu teleport and see its current status with sudo systemctl status teleport.

You can use netstat -lptne to review the port that Teleport is listening on on TCP/IP ports. On auth.example.com, it should look something like this:

auth.example.com ~: sudo netstat -lptne

Active Internet connections (only servers)

Proto Recv-Q Send-Q Local Address State User PID/Program name

tcp6 0 0 :::3024 LISTEN 0 337/teleport

tcp6 0 0 :::3025 LISTEN 0 337/teleport

tcp6 0 0 :::3080 LISTEN 0 337/teleport

tcp6 0 0 :::3022 LISTEN 0 337/teleport

tcp6 0 0 :::3023 LISTEN 0 337/teleport

and node.example.com should look something like this:

node.example.com ~: sudo netstat -lptne

Active Internet connections (only servers)

Proto Recv-Q Send-Q Local Address State User PID/Program name

tcp6 0 0 :::3022 LISTEN 0 337/teleport

See troubleshooting section at the bottom if something is not working.

Adding Users

This portion of the Quick Start Guide should be performed on the auth server, i.e. on auth.example.com

Every user in a Teleport cluster must be assigned at least one role. By default, Teleport comes with several pre-configured roles known as "presets". You can see these roles by executing sudo tctl get roles.

Pay attention to the allow/logins field in the role definition: by default, this role only allows SSH logins as [email protected].

kind: role
metadata:
  name: access
spec:
  allow:
    logins:
    - '{{internal.logins}}'
    - root

You probably want to replace "root" with something else. Let's assume there will be a local UNIX account called "admin" on all hosts. In this case you can dump the role definition YAML into a file and update "allow/logins" to look like this:

allow:
   logins: [admin]
Note

See the Kubernetes Guide and Application Guide for enabling access to additional resources.

Then send it back into Teleport:

sudo tctl create -f role.yaml

Now, lets create a new Teleport user "joe" with "access" role:

sudo tctl users add --roles=access --logins=joe,ubuntu,ec2-user joe

Signup token has been created and is valid for 1 hours. Share this URL with the user:

https://auth.example.com:3080/web/newuser/22e3acb6a0c2cde22f13bdc879ff9d2a

Share the generated sign-up URL with Joe and let him pick a password and configure the second factor authentication. We recommend Google Authenticator which is available for both Android and iPhone.

Assigning Roles

To update user's roles, dump the user resource into a file:

sudo tctl get users/joe > joe.yaml

Edit the YAML file and update the "roles" array. Then, re-insert it back:

sudo tctl create -f joe.yaml

Logging In

Joe now has a local account on a Teleport cluster. The local account is good for administrative purposes but regular users of Teleport Enterprise should be using a Single Sign-On (SSO) mechanism.

But first, lets see how Joe can log into the Teleport cluster. He can do this on his client laptop:

tsh --proxy=auth.example.com --insecure login --user=joe

Note that "--user=joe" part can be omitted if $USER environment variable is "joe".

Notice that tsh client always needs --proxy flag because all client connections in Teleport always must to go through an SSH proxy, sometimes called an "SSH bastion".

Warning

For the purposes of this quickstart we are using the --insecure flag which allows us to skip configuring the HTTPS/TLS certificate for Teleport proxy. Your browser will throw a warning Your connection is not private. Click Advanced, and Proceed to 0.0.0.0 (unsafe) to preview the Teleport UI.

Never use --insecure in production unless you terminate SSL at a load balancer. This will apply to most cloud providers (AWS, GCP and Azure). You must configure a HTTP/TLS certificate for the Proxy. This process has been made easier with Let's Encrypt. We've instructions here.

If successful, tsh login command will receive Joe's user certificate and will store it in ~/.tsh/keys/<proxy> directory.

With a certificate in place, Joe can now interact with the Teleport cluster:

See what hosts are available behind the proxy:

tsh ls

SSH into any host behind the proxy (Unix user 'joe' should already exist on the node):

Log out (this will remove the user certificate from ~/.tsh)

tsh logout

When Teleport's Auth Service receives a request to list Teleport Nodes (e.g., to display Nodes in the Web UI or via tsh ls), it only returns the Nodes that the current user is authorized to view.

For each Node in the user's Teleport cluster, the Auth Service applies the following checks in order and, if one check fails, hides the Node from the user:

  • None of the user's roles contain a deny rule that matches the Node's labels.
  • None of the user's roles contain a deny rule that matches the user's login.
  • At least one of the user's roles contains an allow rule that matches the Node's labels.
  • At least one of the user's roles contains an allow rule that matches the user's login.

If you are not seeing Nodes when expected, make sure that your user's roles include the appropriate allow and deny rules as documented in the Teleport Access Controls Reference.

Configuring SSO

The local account is good for administrative purposes but regular users of Teleport Enterprise should be using a Single Sign-On (SSO) mechanism that use SAML or OIDC protocols.

Take a look at the Single Sign-on chapter to learn the basics of integrating Teleport with SSO providers. We have the following detailed guides for configuring SSO providers:

Any SAML-compliant provider can be configured with Teleport by following the same steps. There are Teleport Enterprise customers who are using Oracle IDM, SailPoint and others.

Run Teleport Enterprise using Docker

We provide pre-built Docker images for every version of Teleport Enterprise. These images are hosted on quay.io.

We currently only offer Docker images for x86_64 architectures.

Note

You will need a recent version of Docker installed to follow this section of the quick start guide.

Warning

This setup will not let you 'SSH into' the node that is running Teleport without additional configuration.

Pick your image

This table gives an idea of how our image naming scheme works. We offer images which point to a static version of Teleport Enterprise, as well as images which are automatically rebuilt every night.

Nightly images point to the latest version of Teleport Enterprise from the three most recent release branches. They are stable, and we recommend their use to easily keep your Teleport Enterprise installation up to date.

Image nameOpen Source or Enterprise?Teleport versionImage automatically updated?Image base
quay.io/gravitational/teleport-ent:10.1.2EnterpriseThe latest version of Teleport Enterprise 10.0YesUbuntu 20.04
quay.io/gravitational/teleport-ent:10.1.2-fipsEnterprise FIPSThe latest version of Teleport Enterprise 10.0 FIPSYesUbuntu 20.04
quay.io/gravitational/teleport-ent:10.1.2EnterpriseThe version specified in the image's tag (i.e. 10.1.2)NoUbuntu 20.04
quay.io/gravitational/teleport-ent:10.1.2-fipsEnterprise FIPSThe version specified in the image's tag (i.e. 10.1.2)NoUbuntu 20.04

For testing, we always recommend that you use the latest release version of Teleport Enterprise, which is currently quay.io/gravitational/teleport-ent:10.1.2.

Quickstart using docker-compose

Note

You will need a recent version of docker-compose installed to follow this section of the quick start guide.

The easiest way to start Teleport Enterprise quickly is to use docker-compose with our teleport-ent-quickstart.yml file:

Download your license file from the Gravitational dashboard and put it in the correct directory.

The file needs to be named "license.pem".

cp ~/downloads/license.pem .

Download the quickstart file from our GitHub repo

curl -Lso teleport-ent-quickstart.yml https://raw.githubusercontent.com/gravitational/teleport/v10.1.2/docker/teleport-ent-quickstart.yml

start teleport quickstart using docker-compose

docker-compose -f teleport-ent-quickstart.yml up
  • The docker-compose quickstart will automatically create a config file for you at ./docker/teleport/config/teleport.yaml
  • This config is mounted into the container under /etc/teleport/teleport.yaml
  • It will also start teleport using this config file, with Teleport's data directory set to ./docker/teleport/data and mounted under /var/lib/teleport
  • It will mount your license file (named license.pem) from the current directory into the Docker container
  • By default, docker-compose will output Teleport's logs to the console for you to observe.
    • If you would rather run the Teleport container in the background, use docker-compose -f teleport-ent-quickstart.yml up -d
    • You can stop the Teleport container using docker-compose -f teleport-ent-quickstart.yml down

Quickstart using docker run

If you'd prefer to complete these steps manually, here's some sample docker run commands:

create local config and data directories for teleport, which will be mounted into the container

mkdir -p ~/teleport/config ~/teleport/data

download your license file from the Gravitational dashboard and put it in the correct directory

the file needs to be named license.pem

cp ~/downloads/license.pem ~/teleport/data/license.pem

generate a sample teleport config and write it to the local config directory

this container will write the config and immediately exit - this is expected

docker run --hostname localhost --rm \ --entrypoint=/bin/sh \ -v ~/teleport/config:/etc/teleport \ quay.io/gravitational/teleport-ent:10.1.2 -c "teleport configure > /etc/teleport/teleport.yaml"

change the path to the license file in the sample config

sed -i 's_/path/to/license-if-using-teleport-enterprise.pem_/var/lib/teleport/license.pem_g' ~/teleport/config/teleport.yaml

start teleport with mounted license, config and data directories, plus all ports

docker run --hostname localhost --name teleport \ -v ~/teleport/config:/etc/teleport \ -v ~/teleport/data:/var/lib/teleport \ -p 3023:3023 -p 3025:3025 -p 3080:3080 \ quay.io/gravitational/teleport-ent:10.1.2

Creating a Teleport user when using Docker quickstart

To create a user inside your Teleport Enterprise container, use docker exec.

This example command will create a Teleport user called testuser which has the access role. Feel free to change these to suit your needs.

docker exec teleport tctl users add --roles=access --logins=root,ec2-user,ubuntu testuser

When you run this command, Teleport will output a URL which you must open to complete the user signup process:

User testuser has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h0m0s:
https://localhost:3080/web/invite/4f2718a52ce107568b191f222ba069f7

NOTE: Make sure localhost:3080 points at a Teleport proxy which users can access.

You can now follow this guide from "Adding Users" onwards to create your user and log into Teleport Enterprise.

Troubleshooting

If Teleport services do not start, take a look at the syslog:

sudo journalctl -fu teleport

Usually the error will be reported there. Common reasons for failure are:

  • Mismatched tokens, i.e. "auth_token" on the node does not match "tokens/node" value on the auth server.
  • Network issues: port 3025 is closed via iptables.
  • Network issues: ports 3025 or 3022 are occupied by another process.
  • Disk issues: Teleport fails to create /var/lib/teleport because the volume is read-only or not accessible.

Getting Help

If something is not working, please reach out to us by creating a ticket in your customer portal. Customers who have purchased the premium support package can also ping us through your Slack channel.