Teleport

Teleport is a SSH infrastructure for clusters of Linux servers. Teleport extends traditional SSH with the following capabilities:

• Provides coordinated and secure access to multiple Linux clusters by multiple teams with different permissions.
• Enforces cluster-specific security policies.
• Includes session record/replay and keeps audit logs.

It also contains a few nice conveniences like built-in command multiplexing, web-based administration and more. Teleport is a standalone executable. It has one external dependency: Etcd

Developer Docs

Take a look at Developer API

Overview

A Teleport daemon needs to be running on every server in a cluster. Each instance assumes one of these roles:

• Auth server
• SSH node
• Web access portal

Auth server

Auth server is connected to Etcd backend and acts as:

• User and host certificate authority server. Read more about SSH authorities in this intro article
• Web and SSH keys access checker - it grants revokes access to users
• Audit logs collector, every other SSH node ships access logs to it

Note: Auth server does not itself provide any support for interactive sessions and remote command execution

SSH node

SSH node is a stateless node that connects to the the auth server authenticating using it's host certificate and relies on Auth server for authorization and authentication.

Web access portal

Web access portal is stateless too, it connects to the auth server and provides SSH access, view of the logs and key management interfaces.

Installation

Teleport is currently a private project and should be cloned from the repository.

Prerequisites

• go >= 1.4.2
• etcd >= v2.0.10

Clone the latest master

mkdir -p $(GOPATH)/src/github/gravitational
cd $(GOPATH)/src/github/gravitational
git clone git@github.com:gravitational/teleport.git

Compile

make install

This should install the binaries, check that the binaries are installed.

ls ${GOPATH}/bin/tctl ${GOPATH}/bin/teleport

Auth Server

# create the directory where auth server will keep it's local state
mkdir -p /var/lib/teleport-auth

# start teleport binary with auth role enabled
teleport -auth\
         -authBackend=etcd\
         -authBackendConfig='{"nodes": ["http://127.0.0.1:4001"], "key": "/teleport"}'\
         -authDomain=example.com\
         -authSSHAddr=tcp://0.0.0.0:32000\
         -log=console\
         -logSeverity=INFO\
         -dataDir=/var/lib/teleport-auth\
         -fqdn=auth.example.com

Note: authSSHAddr sets up a special-purpose SSH-powered API endpoint that the auth server exposes for nodes and web portals to check access.

SSH Server

On the first connection attempt SSH nodes will attempt to connect to the auth server and register itself. Get a one-time security token from the auth server for a SSH node to connect to the server:

Step 1. Get the token

This command will generate a one time secure token allowing server node1.example.com to register with the server within the next 120 seconds.

tctl token generate -fqdn=node1.example.com

Step 2. Start the SSH node

Pass the token from the step 1 and pass it to the teleport SSH node on start:

# create a directory for the local node state
mkdir -p /var/lib/teleport-node

# start the server
TELEPORT_SSH_TOKEN=<token here> teleport -ssh\
             -log=console\
             -logSeverity=INFO\
             -dataDir=/var/lib/teleport-node\
             -fqdn=node1.example.com\
             -authServer=tcp://auth.example.com:32000
             -sshAddr=tcp://0.0.0.0:33000

SSH node will use the token to connect to the auth server and provision the signed SSH host certificate and private key. The subsequent starts/restart will use the host certificates to authenticate with the Auth server.

Web Server

Control panel node is optional, and is only needed if you want to access the cluster via web interface.

    # create a directory for the local node state
    mkdir -p /var/lib/teleport-cp

	teleport -cp\
             -cpDomain=example.com\
             -log=console\
             -logSeverity=INFO\
             -dataDir=/var/lib/teleport-cp\
             -fqdn=cp.gravitational.io\
             -authServer=tcp://auth.gravitational.io:32000

Note: Unlike SSH node, CP node does not need to use any provisioning step, as it's just a web interface using SSH auth server APIs.

Step 1. Get the token

This command will generate a one time secure token allowing server node1.example.com to register with the server within the next 120 seconds.

tctl token generate -fqdn=node1.example.com

Step 2. Start the SSH node

Pass the token from the step 1 and pass it to the teleport SSH node on start:

# create a directory for the local node state
mkdir -p /var/lib/teleport-node

# start the server
TELEPORT_SSH_TOKEN=<token here> teleport -ssh\
             -log=console\
             -logSeverity=INFO\
             -dataDir=/var/lib/teleport-node\
             -fqdn=node1.example.com\
             -authServer=tcp://auth.example.com:32000
             -sshAddr=tcp://0.0.0.0:33000

SSH node will use the token to connect to the auth server and provision the signed SSH host certificate and private key. The subsequent starts/restart will use the host certificates to authenticate with the Auth server.

SSH access

Connecting to Teleport is like connecting to any other SSH server, except that it does not support password and host based auth, and only works with keys signed by the authority.

Sign the SSH key

If you don't have they key yet:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

To sign the key, you can use the tctl command on the auth server:

tctl user upsert_key -user=user -keyid=user-key1 -key=user.pub

Teleport user CA (certificate authority) will sign the key and returned the signed certificate. You can place it near the private and public keys in file user-cert.pub and use it to connect to the server.

Add the keys to agent

SSH agent is a little program that holds the keys in memory and authenticates on your behalf. Check if ssh agent is running:

pidof ssh-agent

If the command above returns nothing, start the agent:

eval $(ssh-agent)

Add keys to the agent:

ssh-add /<path-to-key>/user

Check if the keys are loaded

ssh-add -l
2048 8f:c2:cf:85:c4:02:7a:f9:73:ae:c7:62:ae:c0:36:04 rsa w/o comment (RSA)
2048 8f:c2:cf:85:c4:02:7a:f9:73:ae:c7:62:ae:c0:36:04 rsa w/o comment (RSA-CERT)

Log in:

ssh -p 33000 node1.example.com

Trusting Host CA

You may have noticed the following warning when connecting to the host:

The authenticity of host '[node1.gravitational.io]:33000 ([127.0.0.1]:33000)' can't be established.
RSA key fingerprint is 9d:ff:8b:aa:b5:af:70:33:90:a8:1c:1e:85:af:02:a6.
Are you sure you want to continue connecting (yes/no)

This warning means that your client have not seen this host before and is not sure if it's trusted or not. It will be displayed each time you log in to the server that was not seen before.

This is quite annoying to deal with, and thankfully, there's a solution for it. All host keys used by teleport are signed by the host authority. Instead of validating the keys, you can validate the authority.

Get the host CA certificate

# from the auth server:
tctl hostca pubkey

Copy the certificate and write this line to your home folder's .ssh/known_hosts:

@cert-authority *.example.com <certificate-key-here>

This line will tell the SSH client to trust all hosts whose public keys are signed by this authority.

Web access

Teleport allows to access the cluster via optional web portal handled by CP server.

Create a password

Grant user web access using auth server user api

 tctl user set_pass -user=alex -pass=pwd123

Now users can log in using their usernames and passwords into the portal