Skip to content

Latest commit

 

History

History
460 lines (338 loc) · 15.7 KB

getting-started.mdx

File metadata and controls

460 lines (338 loc) · 15.7 KB
title description
Get Started with Teleport Enterprise
Learn how to deploy your first Teleport Enterprise cluster.

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:

Tool Description
tctl Cluster administration tool used to perform tasks such as inviting Nodes to a cluster and managing user accounts.
tsh Allows users to authenticate and access resources via their local machine.
Web UI You 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.

(!docs/pages/includes//cloud/call-to-action.mdx!)

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.

(!docs/pages/includes/dns.mdx!)

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-v(=teleport.version=)-linux-amd64-fips-bin.tar.gz.sha256
# <checksum> <filename>
$ curl -O https://get.gravitational.com/teleport-ent-v(=teleport.version=)-linux-amd64-fips-bin.tar.gz
$ shasum -a 256 teleport-ent-v(=teleport.version=)-linux-amd64-fips-bin.tar.gz
# Verify that the checksums match
$ tar -xzf teleport-ent-v(=teleport.version=)-linux-amd64-fips-bin.tar.gz
$ cd teleport-ent
$ sudo ./install

$ curl https://get.gravitational.com/teleport-ent-v(=teleport.version=)-linux-amd64-bin.tar.gz.sha256
# <checksum> <filename>
$ curl -O https://get.gravitational.com/teleport-ent-v(=teleport.version=)-linux-amd64-bin.tar.gz
$ shasum -a 256 teleport-ent-v(=teleport.version=)-linux-amd64-bin.tar.gz
# Verify that the checksums match
$ tar -xzf teleport-ent-v(=teleport.version=)-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.

(!docs/pages/includes/tls-certificate-setup.mdx!)

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

(!docs/pages/includes/enterprise/obtainlicense.mdx!)

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:

Role Description
access Can access resources in your infrastructure, such as Teleport Nodes, applications, and Kubernetes clusters
auditor Can view audit logs and session recordings.
editor Can 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 following commands to download and run the Teleport installer:

$ curl -O https://get.gravitational.com/teleport-ent-(=teleport.version=).pkg
# Installs on Macintosh HD
$ sudo installer -pkg teleport-ent-(=teleport.version=).pkg -target / 
# Password:
# installer: Package name is teleport-ent-(=teleport.version=)
# 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:

(!docs/pages/includes/install-linux.mdx!)

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-v(=teleport.version=)-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-v(=teleport.version=)-windows-amd64-bin.zip https://get.gravitational.com/teleport-v(=teleport.version=)-windows-amd64-bin.zip
$ certUtil -hashfile teleport-v(=teleport.version=)-windows-amd64-bin.zip SHA256
# SHA256 hash of teleport-v(=teleport.version=)-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-v(=teleport.version=)-windows-amd64-bin\teleport\tsh.exe.

$ Expand-Archive teleport-v(=teleport.version=)-windows-amd64-bin.zip
$ cd teleport-v(=teleport.version=)-windows-amd64-bin\teleport
$ .\tsh.exe version
Teleport v(=teleport.version=) git:v(=teleport.version=) go(=teleport.golang=)

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

(!docs/pages/includes/node-logins.mdx!)

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:

$ tsh ssh ubuntu@mynode

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.