Fork me on GitHub

Teleport

Get Started with Teleport Enterprise

Improve

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

You will be deploying three Teleport services on a single host:

  • The Auth Service stores user accounts and your cluster configuration. It provides authentication and authorization for every Teleport service and every user in your cluster.

  • The Proxy Service routes client connection requests to the appropriate Teleport services and serves the Teleport Web UI, which you can use to access resources or manage the cluster.

  • The SSH Service is an SSH server implementation that provides seamless access to Linux hosts in your cluster.

    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.

    Other Teleport services provide access to remote desktops, Kubernetes clusters, applications, and databases.

You will install the teleport binary, which runs runs all three of these services by default.

You will also use the following client tools:

ToolDescription
tctlCluster administration tool used to perform tasks such as inviting Nodes to a cluster and managing user accounts.
tshAllows users to authenticate and access resources via their local machine.
Web UIYou can use the Teleport Web UI to access resources in your cluster by navigating to the public address of your Teleport Proxy Service in your browser.

Teleport Cloud takes care of this setup for you so you can provide secure access to your infrastructure right away.

Get started with a free trial of Teleport Cloud.

Prerequisites

  • A Teleport Enterprise account. If you do not have one, use our signup form to schedule a demo with the Teleport Sales Team.
  • A Linux machine with only port 443 open to ingress traffic. You must be able to install and run software on the machine. Either configure access to your machine via SSH for the initial setup (and open an SSH port in addition port 443) or enter the commands in this guide into an Amazon EC2 user data script, Google Compute Engine startup script, or similar.
  • A two-factor authenticator app such as Authy, Google Authenticator, or Microsoft Authenticator.
  • python3 installed on your Linux machine. We will use this to run a simple HTTP file server, so you can use another HTTP server if you have one installed.

You must also have one of the following:

  • A registered domain name.
  • An authoritative DNS nameserver managed by your organization, plus some means of obtaining a TLS certificate and private key for your Teleport deployment. If using this approach, ensure that your browser is configured to use your organization's nameserver.

Step 1/5. Create DNS records

Teleport uses TLS to provide secure access to its Proxy Service and Auth Service, and this requires a domain name that clients can use to verify Teleport's certificate.

Set up two A DNS records: tele.example.com for all traffic and *.tele.example.com for web apps using Application Access. We are assuming that your domain name is example.com. Use your own subdomain instead of tele.

Teleport assigns a subdomain to each application you have configured for Application Access (e.g., grafana.teleport.example.com), so you will need to ensure that a DNS A record exists for each application-specific subdomain so clients can access your applications via Teleport.

You should create either a separate DNS A record for each subdomain or a single record with a wildcard subdomain such as *.teleport.example.com. This way, your certificate authority (e.g., Let's Encrypt) can issue a certificate for each subdomain, enabling clients to verify your Teleport hosts regardless of the application they are accessing.

Execute the following commands on the host where you are running the Teleport Proxy Service:

Tip for finding AWS zone id by the domain name.

MYIP="$(curl https://ipv4.icanhazip.com/)"
MYZONE_DNS="example.com"
MYZONE=$(aws route53 list-hosted-zones-by-name --dns-name=${MYZONE_DNS?} | jq -r '.HostedZones[0].Id' | sed s_/hostedzone/__)

The fully qualified domain name for your Teleport Proxy Service.

These commands will also create an A record for a wildcard subdomain.

MYDNS="tele.example.com"

Create a JSON file changeset for AWS.

jq -n --arg ip ${MYIP?} --arg dns ${MYDNS?} '{"Comment": "Create records", "Changes": [{"Action": "CREATE","ResourceRecordSet": {"Name": $dns, "Type": "A", "TTL": 300, "ResourceRecords": [{ "Value": $ip}]}},{"Action": "CREATE", "ResourceRecordSet": {"Name": ("*." + $dns), "Type": "A", "TTL": 300, "ResourceRecords": [{ "Value": $ip}]}}]}' > myrecords.json

Review records before applying.

cat myrecords.json | jq

Apply the records and capture change id

CHANGEID=$(aws route53 change-resource-record-sets --hosted-zone-id ${MYZONE?} --change-batch file://myrecords.json | jq -r '.ChangeInfo.Id')

Verify that change has been applied

aws route53 get-change --id ${CHANGEID?} | jq '.ChangeInfo.Status'

"INSYNC"

MYZONE="myzone"

The fully qualified domain name for your Teleport Proxy Service.

These commands will also create an A record for a wildcard subdomain.

MYDNS="tele.example.com"
MYIP="$(curl https://ipv4.icanhazip.com/)"

gcloud dns record-sets transaction start --zone="${MYZONE?}"
gcloud dns record-sets transaction add ${MYIP?} --name="${MYDNS?}" --ttl="30" --type="A" --zone="${MYZONE?}"
gcloud dns record-sets transaction add ${MYIP?} --name="*.${MYDNS?}" --ttl="30" --type="A" --zone="${MYZONE?}"
gcloud dns record-sets transaction describe --zone="${MYZONE?}"
gcloud dns record-sets transaction execute --zone="${MYZONE?}"
Tip

You can use dig to make sure that DNS records are propagated:

dig tele.example.com

Step 2/5. Run a simple web service

Create a directory on your Linux machine called demo-app and run the following command:

cat<<EOF>>demo-app/index.html<!DOCTYPE html><html><head><title>Welcome!</title><head><body><h1>Welcome to your Teleport cluster!</h1></body></html>EOF

Run a simple HTTP service on port 9000 that returns your welcome page:

nohup python3 -m http.server 9000 --directory demo-app &

Since port 9000 is not open on your Linux host, there is currently no way to access the web service from your local machine. We will configure Teleport to enable you to access the web service securely.

Step 3/5. Set up Teleport

Install the teleport binary

On the host where you will run your Teleport services, run the following commands to install the teleport binary:

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

curl https://get.gravitational.com/teleport-ent-v10.3.1-linux-amd64-fips-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://get.gravitational.com/teleport-ent-v10.3.1-linux-amd64-fips-bin.tar.gz
shasum -a 256 teleport-ent-v10.3.1-linux-amd64-fips-bin.tar.gz

Verify that the checksums match

tar -xzf teleport-ent-v10.3.1-linux-amd64-fips-bin.tar.gz
cd teleport-ent
sudo ./install
curl https://get.gravitational.com/teleport-ent-v10.3.1-linux-amd64-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://get.gravitational.com/teleport-ent-v10.3.1-linux-amd64-bin.tar.gz
shasum -a 256 teleport-ent-v10.3.1-linux-amd64-bin.tar.gz

Verify that the checksums match

tar -xzf teleport-ent-v10.3.1-linux-amd64-bin.tar.gz
cd teleport-ent
sudo ./install

Configure Teleport

Generate a configuration file for Teleport using the teleport configure command. This command requires information about a TLS certificate and private key.

If you are exposing your Teleport host to the internet, we recommend using Let's Encrypt to receive your key and certificate automatically. For private networks or custom deployments, use your own private key and certificate.

Let's Encrypt verifies that you control the domain name of your Teleport cluster by communicating with the HTTPS server listening on port 443 of your Teleport Proxy Service.

You can configure the Teleport Proxy Service to complete the Let's Encrypt verification process when it starts up.

On the host where you will start the Teleport Auth Service and Proxy Service, run the following commands, where tele.example.com is the domain name of your Teleport cluster and [email protected] is an email address used for notifications (you can use any domain):

DOMAIN=tele.example.com
teleport configure --acme --acme-email=${EMAIL?} --cluster-name=${DOMAIN?} | \ sudo tee /etc/teleport.yaml > /dev/null

The --acme, --acme-email, and --cluster-name flags will add the following settings to your Teleport configuration file:

proxy_service:
  enabled: "yes"
  web_listen_addr: :443
  public_addr: tele.example.com:443
  acme:
    enabled: "yes"
    email: [email protected]

Port 443 on your Teleport Proxy Service host must allow traffic from all sources.

On your Teleport host, place a valid private key and a certificate chain in /var/lib/teleport/privkey.pem and /var/lib/teleport/fullchain.pem respectively.

The leaf certificate must have a subject that corresponds to the domain of your Teleport host, e.g., *.teleport.example.com.

Configure Teleport, changing the values of the --cluster-name and --public-addr flags to match the domain name of your Teleport host.

sudo teleport configure -o file \ --cluster-name=tele.example.com \ --public-addr=tele.example.com:443 \ --cert-file=/var/lib/teleport/fullchain.pem \ --key-file=/var/lib/teleport/privkey.pem

Next, configure Teleport to provide secure access to your web service. Edit your Teleport configuration file (/etc/teleport.yaml) to include the following, replacing teleport.example.com with the domain name of your Teleport cluster.

app_service:
    enabled: yes
    apps:
    - name: "demo"
      uri: "http://localhost:9000"
      public_addr: "demo.teleport.example.com"

Obtain your license file

The teleport binary reads a local license file to authenticate your Teleport Enterprise account.

To obtain your license file, visit the Teleport customer dashboard and log in. Click "DOWNLOAD LICENSE KEY". You will see your current Teleport Enterprise account permissions and the option to download your license file:

License File modal

Save your license file on the host where you will install Teleport at the path, /var/lib/teleport/license.pem.

Start Teleport

On the host where you are running Teleport, generate a systemd unit file for Teleport and save it in /etc/systemd/system/teleport.service:

sudo teleport install systemd -o /etc/systemd/system/teleport.service

Enable the Teleport service and start Teleport in the background:

sudo systemctl enable teleport
sudo systemctl start teleport

Confirm that the teleport service has started:

$ sudo systemctl status teleport

Get information about your Teleport deployment

You can review the logs of the Teleport service with the following command:

journalctl -fu teleport

Run the following command to review the ports that Teleport is listening on:

sudo netstat -lptne

The output should look something like this:

sudo netstat -lptne | grep teleport

tcp6 0 0 :::443 :::* LISTEN

0 168760 29504/teleport

tcp6 0 0 :::3022 :::* LISTEN

0 167812 29504/teleport

tcp6 0 0 :::3025 :::* LISTEN

0 168741 29504/teleport

Step 4/5. Add a local user

Create a user

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:

RoleDescription
accessCan access resources in your infrastructure, such as Teleport Nodes, applications, and Kubernetes clusters
auditorCan view audit logs and session recordings.
editorCan modify cluster configuration.

You can see the full configurations for these roles by executing the following command on the host running Teleport:

sudo tctl get roles

On the host where you are running Teleport, create a Teleport user called myuser with the access role and the ubuntu login. This user can log in to any host in your infrastructure as ubuntu (choose a login that matches a user account on your Linux host):

sudo tctl users add --roles=access --logins=ubuntu myuser

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

Navigate to the link displayed in your terminal, pick a password, and configure second factor authentication.

Log in as your new user

tsh is our client tool. It helps you log in to Teleport clusters and obtain short-lived credentials. It can also be used to list resources registered with Teleport, such as servers, applications, and Kubernetes clusters.

Install tsh on your local machine:

Run the follwoing commands to download and run the Teleport installer:

curl -O https://get.gravitational.com/teleport-ent-10.3.1.pkg

Installs on Macintosh HD

sudo installer -pkg teleport-ent-10.3.1.pkg -target /

Password:

installer: Package name is teleport-ent-10.3.1

installer: Upgrading at base path /

installer: The upgrade was successful.

which teleport

/usr/local/bin/teleport

Run the following commands to install Teleport binaries on your client system, including tsh:

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 v10. You'll need to update this

file for each major release of Teleport.

Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'

and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.

Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67

echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \ https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v10" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport

Source variables about OS version

source /etc/os-release

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

file for each major release of Teleport.

Note: if using a fork of RHEL/CentOS or Amazon Linux you may need to use '$ID_LIKE'

and the codename your distro was forked from instead of '$ID'

Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L133-L153

sudo yum-config-manager --add-repo $(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v10/teleport.repo")
sudo yum install teleport
curl https://get.gravitational.com/teleport-v10.3.1-linux-amd64-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://get.gravitational.com/teleport-v10.3.1-linux-amd64-bin.tar.gz
shasum -a 256 teleport-v10.3.1-linux-amd64-bin.tar.gz

Verify that the checksums match

tar -xzf teleport-v10.3.1-linux-amd64-bin.tar.gz
cd teleport
sudo ./install
curl https://get.gravitational.com/teleport-v10.3.1-linux-arm-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://get.gravitational.com/teleport-v10.3.1-linux-arm-bin.tar.gz
shasum -a 256 teleport-v10.3.1-linux-arm-bin.tar.gz

Verify that the checksums match

tar -xzf teleport-v10.3.1-linux-arm-bin.tar.gz
cd teleport
sudo ./install
curl https://get.gravitational.com/teleport-v10.3.1-linux-arm64-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://get.gravitational.com/teleport-v10.3.1-linux-arm64-bin.tar.gz
shasum -a 256 teleport-v10.3.1-linux-arm64-bin.tar.gz

Verify that the checksums match

tar -xzf teleport-v10.3.1-linux-arm64-bin.tar.gz
cd teleport
sudo ./install

Using this APT repo may result in breaking upgrades upon "apt upgrade" as all major versions will be

published under the same component. We recommend following the instructions in the

"Debian/Ubuntu (DEB)" tab instead.

Download Teleport's PGP public key

sudo curl https://deb.releases.teleport.dev/teleport-pubkey.asc \ -o /usr/share/keyrings/teleport-archive-keyring.asc

Add the Teleport APT repository

echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] https://deb.releases.teleport.dev/ stable main" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport
sudo yum-config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
sudo yum install teleport

Optional: Using DNF on newer distributions

$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo

$ sudo dnf install teleport

Most tsh features are supported for Windows 10 1607+. The tsh ssh command can be run under cmd.exe, PowerShell, and Windows Terminal.

To install tsh on Windows, run the following commands in PowerShell:

Get the expected checksum for the Windows tsh package

$Resp = Invoke-WebRequest https://get.gravitational.com/teleport-v10.3.1-windows-amd64-bin.zip.sha256

PowerShell will return the binary representation of the response content

by default, so you need to convert it to a string

[System.Text.Encoding]::UTF8.getstring($Resp.Content)

<checksum> <filename>

curl -O teleport-v10.3.1-windows-amd64-bin.zip https://get.gravitational.com/teleport-v10.3.1-windows-amd64-bin.zip
certUtil -hashfile teleport-v10.3.1-windows-amd64-bin.zip SHA256

SHA256 hash of teleport-v10.3.1-windows-amd64-bin.zip:

<checksum>

CertUtil: -hashfile command completed successfully.

After you have verified that the checksums match, you can extract the archive. The executable will be available at teleport-v10.3.1-windows-amd64-bin\teleport\tsh.exe.

Expand-Archive teleport-v10.3.1-windows-amd64-bin.zip
cd teleport-v10.3.1-windows-amd64-bin\teleport
.\tsh.exe version

Teleport v10.3.1 git:v10.3.1 go1.18

Make sure to move tsh.exe into your PATH.

Use tsh to log in to your Teleport cluster as myuser, replacing auth.example.com with the domain name you configured earlier:

tsh --proxy=auth.example.com login --user=myuser

Note that you can omit the --user flag if the $USER environment variable is equal to your Teleport username.

If successful, the tsh login command will retrieve a user certificate for myuser and store it in the ~/.tsh/keys/<proxy> directory.

With a certificate in place, myuser can now interact with the Teleport cluster.

Step 5/5. Access resources

You have now completed setting up Teleport and signed in to your cluster. Now you can use Teleport to quickly access resources.

Visit your demo website

Now that you have logged in to Teleport, you can see the demo website you started earlier. Visit https://demo.teleport.example.com, replacing teleport.example.com with the domain name of your Teleport cluster. You can only visit the website if you have authenticated with your cluster.

You can use the Teleport Application Service to configure access to any web application in your private network, including HTTP management endpoints for popular infrastructure technologies.

SSH into your Node

You also configured the Teleport SSH Service, meaning that you can easily access your Linux machine after logging in to Teleport.

See the logins you can use to access a Node:

tsh status

> Profile URL: https://teleport.example.com:443

Logged in as: teleport-admin

Cluster: teleport.example.com

Roles: access, editor

Logins: root, ubuntu, ec2-user

Kubernetes: enabled

Valid until: 2022-04-26 04:55:59 -0400 EDT [valid for 11h38m0s]

Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty

List all SSH servers connected to Teleport:

tsh ls

Node Name Address Labels

---------------- -------------- -------------------------------------

mynode 127.0.0.1:3022 env=example,hostname=mynode

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.

SSH into your Node, replacing mynode with one of the Nodes listed by the tsh ls command and ubuntu with the login on your Linux host that you configured myuser to access:

Next steps

Deploy on Kubernetes

This guide shows you how to install Teleport Enterprise on a virtual machine. If you are using a Kubernetes-based environment, see our Getting Started Guide for how to deploy Teleport on Kubernetes.

Configure RBAC

The preset access role we assigned to a user in this guide is probably too permissive for your environment. Read our guide to configuring Teleport roles to set up more granular access controls.

Configure SSO

In this guide, we created a local user stored on the Teleport Auth Service. For on and offboarding users at scale, you should use one of Teleport's Single Sign-On integrations.

Take a look at our Single Sign-On guide to learn the basics of integrating Teleport with SSO providers.

You can configure any SAML- or OIDC-compliant identity provider to enable SSO for Teleport. There are Teleport Enterprise customers who are using Oracle IDM, SailPoint, and others.

Configure Access Requests

With Teleport Access Requests you can provide your users limited access to resources by default. Your users can then access elevated privileges on a temporary basis, minimizing the risk that an attacker will compromise an admin account.

Read our guide to setting up Access Requests.

You can then take advantage of Teleport's Access Request plugins so users can request and review Access Requests using your existing communication workflows.

Troubleshooting

If Teleport services do not start, take a look at the teleport service's logs:

sudo journalctl -fu teleport

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

  • Network issues: port 443 is closed via iptables or 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.