Getting started with Teleport

Features

According to Teleport’s elevator pitch, it is a single Access plane to securely access all of your servers, databases, applications or Kubernetes clusters. It provides fine-grained role-based access control and many auditing possibilities. One of its killer features (in my opinion) is the session recording: Each login on a server is recorded and can be replayed just like a video, but you can also copy things from that recording as if it were a text file. Fancy!

In addition to all of this there is the possibility to enable two-factor-authentication, using both OTP tokens or hardware devices like U2F or FIDO2 keys – and many more nice things.

Of course, access to a server’s CLI is easy and secure via OpenSSH. Even auditing and session recording can be done with e.g. sudo features, but need to be configured. On each and every server. SSH will not go away, but why not use something that is a little easier to configure and easier to use? Sounds good, right? Let’s get started.

The architecture

The Teleport architecture consists of three things: – a central server that users are connecting to and authenticating against (think single-sign-on…) – nodes that are configured in this cluster and can be connected to – users trying to access these nodes, either via UI or via the tsh utility

The central server is the brain of the whole outfit. In terms of the configuration file, this is the auth_service.

Each node that you want to access in a SSH-like style needs to be configured to run the ssh_service.

There are other services that we can configure, but for now those two should be enough. We will cover the others in a later part of this series.

Installation of the central server

To provide the central server instance, you can either use a linux server or a virtual machine, or you can deploy it into a Kubernetes cluster. For the sake of simplicity, we will use a virtual machine for both the server and an example node. The machine should be reachable via some kind of DNS name. For your first steps, you can configure the name in your laptop’s /etc/hosts file as well as on the node that we will configure later. The excellent teleport documentation tells us to configure both a hostname (teleport.example.com) and a wildcard (*.tele.example.com) to point to the server. Port 443 needs to be open on the server, which should not be a problem in most environments. On the machine itself it needs to be configured in the firewall, e.g. firewalld or ufw or similar.

The first step is to install teleport. Most linux distributions provide packages – if there are none or they are outdated, have a look at the install section of the documentation.

The documentation shows a lot of sudo teleport start ... commands, that will block your terminal until you exit them. I generally prefer to just prepare a configuration file and then start the systemd service for teleport. That is also easier to explain.

So, after you installed teleport, prepare a file called /etc/teleport.yaml with the following content:

version: v2
teleport:
  nodename: teleport-server
  data_dir: /var/lib/teleport
  log:
    output: stderr
    severity: INFO
    format:
      output: text
  ca_pin: []
  diag_addr: ""
auth_service:
  enabled: "yes"
  listen_addr: 0.0.0.0:3025
  cluster_name: getting_started_with_teleport
  proxy_listener_mode: multiplex
  tokens:
    - "node:very_insecure_token_that_should_not_be_used"
ssh_service:
  enabled: "yes"
  labels:
    env: example
    type: server
  commands:
  - name: hostname
    command: [hostname]
    period: 1m0s
  - name: operating_system
    command: ["bash", "-c", "awk -F'=' '/^PRETTY/ {print $2}' /etc/os-release"]
    period: 30m
proxy_service:
  enabled: "yes"
  web_listen_addr: 0.0.0.0:443
  public_addr: teleport.example.com:443
  https_keypairs:
  - key_file: /etc/pki/tls/private/teleport-server.key
    cert_file: /etc/pki/tls/private/teleport-server.crt
  acme: {}

Yes, that is a lot to digest. Let’s look at it one by one (and most of it is just the defaults, so bear with me).

We tell teleport how this node is called:

  nodename: teleport-server

After some minor interesting things we configure the auth_service:

auth_service:
  enabled: "yes"
  listen_addr: 0.0.0.0:3025
  cluster_name: getting_started_with_teleport
  tokens:
    - "node:very_insecure_token_that_should_not_be_used"

It should be enabled, making this a central server. It listens on port 3025. The cluster is called getting_started_with_teleport. We also configure a token of type node. In reality this should of course be some random-character-string instead of very_insecure_token_that_should_not_be_used. The type tells teleport that this token is to be used for joining nodes only.

The next section is for the ssh_service: We enable it, and provide some static labels like env or type. Those will help you later to both find your nodes and configure access to them.

---

Then we have some commands that are being used to also set labels. Those will be dynamic labels, one for the hostname and one for the operation system’s pretty name from /etc/os-release. *****

Next up is the proxy_service, which listens on port 443. The public address will be our hostname teleport.example.com. Most readers will not be surprised to find that we need to provide a certificate and a corresponding private key for a service that listens on port 443. Those can either be created by the user (self-signed) or by your company’s CA. In case you want to make use of free Let’s Encrypt certificates, have a look at the documentation.

So, what does that give us? It gives us a server that runs the auth_service to authenticate against, the proxy_service to reach the WebUI. Oh, and we could log into the server via Teleport SSH.

Feel free to start the teleport service, most probably using systemctl start teleport.service. If you then open https://teleport.example.com in your browser, you are asked to login with user credentials. Huh, we did not yet provide user credentials? Enter the tctl command…

Interacting with the teleport server via tctl

On the server, you can configure Teleport with the tctl command. Later on, most things can be done in the WebUI, but for creating our first user we need to use tctl.

tctl users add first_user --roles auditor,editor,access --logins root,vagrant,db_admin

This command creates a user called first_user that gets some roles and logins. Let’s have a look at what they do.

The roles are used for the role-based access control feature. Any user with the access role can access things, while editor grants permissions to edit settings in Teleport. The auditor role gives you access to the sensitive information stored in various auditing features of Teleport.

The logins are used once the user wants to access a node via Teleport SSH. You can only connect to given usernames, in OpenSSH terminology this would be the list of users in the ssh username@server command. So, our first_user can connect to a node as the root user, but not as the web_admin user. You get the idea.

The tctl command will show some output including a link. Open that link in a browser, click on Get started and then provide a password for the user. Note that you need to setup two-factor-authentication using a authenticator app like AndOTP, Authy, Google Authenticator etc.

User "first_user" has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h:
https://teleport.example.com:443/web/invite/b6ae21c3961e1ed833cf500cfbd22158

NOTE: Make sure teleport.example.com:443 points at a Teleport proxy which users can access.

Side note: You could turn this off in the teleport.yaml by using the following stanza, but that would contradict the whole idea of a secure login, right?

auth_service:
[...]
  authentication:
    second_factor: off

After you specified the password and set up 2FA, you should be logged in. Nice.

Accessing the server via Teleport SSH

Once you are logged in, you should see a menu on the left side and your user’s icon on the top right. If you click on Servers in the menu, you should get a list of servers that you can connect to. In our case, it is only the Teleport server node (remember, we enabled the ssh_service).

Click on connect, and you will be asked for the username you want to log in as. Select root and you should see a root terminal in your browser. Try some (harmless!) commands, then exit the session.

Then head over to Activity in the menu, and on to Session Recordings. You should see a session, and once you hit Play on the right side you should see a replay of your session, with all commands, all output, everything. Try the time slider on the bottom to go forward or backward, try to copy things. Nice, isn’t it?

Log back into the server, switch back to the UI and open the Active Sessions: You’ll see your session on the server. See the Options button on that session? There is an option to join an existing session. Think pair programming. Think debugging together. There are many uses cases.

OK, let’s add another node now.

Configure a node

Head over to your other virtual machine, install teleport and create a teleport.yaml like this:

version: v2
teleport:
  nodename: my-first-node
  data_dir: /var/lib/teleport
  log:
    output: stderr
    severity: INFO
    format:
      output: text
  auth_token: "very_insecure_token_that_should_not_be_used"
  auth_servers:
    - teleport.example.com:443
auth_service:
  enabled: "no"
proxy_service:
  enabled: "no"
app_service:
  enabled: "no"
ssh_service:
  enabled: "yes"
  labels:
    env: example
    type: node
  commands:
  - name: hostname
    command: [hostname]
    period: 1m0s
  - name: operating_system
    command: ["bash", "-c", "awk -F'=' '/^PRETTY/ {print $2}' /etc/os-release"]
    period: 30m

The teleport: section should look familiar, there are just two things different here (ok, three, the hostname is also different…): – there is a section for the auth_servers: where you specify the central server’s name – you specify an auth_token in this section, while it was in the auth_service section on the server

After that, we disable all services that we do not want this node to run: auth_service, proxy_service and ssh_service. The ssh_service is enabled and configured the same way as on the server.

Start the teleport client, head over to your WebUI and have a look in the Servers tab: Congratulations, you should now have two nodes that you can connect to.

What’s next?

So far we only scratched the surface of what Teleport can do. For those of you who do not want to wait until the next part of this series, check out the very informative series of videos that David Flanagan aka Rawkode did.

In the next part I will show you what other things you can connect to via Teleport – things like Kubernetes clusters or applications. Then we will need to look at roles and role-based access control.

Now go and play with Teleport. Feel free to report back how you liked it.