Teleport

Getting Started with Teleport Application Access

Improve

Getting started with Teleport Application Access

Length: 08:20

Getting Started

Let's connect to Grafana using Teleport Application Access in three steps:

Launch Grafana in a Docker container.
Install Teleport and configure it to proxy Grafana.
Access Grafana through Teleport.

Prerequisites

We will use Docker to launch Grafana in a container. Alternatively, if you have another web application you'd like to protect with App Access, you can use that instead.
We will assume your Teleport cluster is accessible at teleport.example.com and *.teleport.example.com. Configured DNS records are required to automatically fetch a Let's Encrypt certificate.

Step 1/3. Start Grafana

We've picked Grafana for this tutorial since it's very easy to run with zero configuration required. If you have another web application you'd like to expose, skip over to Step 2.

Grafana can be launched in a Docker container with a single command:

docker run -d -p 3000:3000 grafana/grafana

Step 2/3. Install and configure Teleport

Download the latest version of Teleport for your platform from our downloads page.

Teleport requires a valid TLS certificate to operate and can fetch one automatically using Let's Encrypt ACME protocol.

We will assume that you have configured DNS records for teleport.example.com and *.teleport.example.com to point to the Teleport node.

Tip

The examples below may include the use of the sudo keyword, token UUIDs, and users with admin privileges to make following each step easier when creating resources from scratch.

Generally:

We discourage using sudo in production environments unless it's needed.
We encourage creating new, non-root, users or new test instances for experimenting with Teleport.
We encourage adherence to the Principle of Least Privilege (PoLP) and Zero Admin best practices. Don't give users the admin role when giving them the more restrictive access,editor roles will do instead.
Saving tokens into a file rather than sharing tokens directly as strings.

Learn more about Teleport Role-Based Access Control best practices.

Let's generate a Teleport config with ACME enabled:

sudo teleport configure --cluster-name=teleport.example.com --acme [email protected] -o file

Web Proxy Port

Teleport uses TLS-ALPN-01 ACME challenge to validate certificate requests which only works on port 443. Make sure your Teleport proxy is accessible on port 443 when using ACME for certificate management.

Now start Teleport and point it to the application endpoint:

sudo teleport start \  --roles=proxy,auth,app \  --app-name=grafana \  --app-uri=http://localhost:3000

Make sure to update --app-name and --app-uri accordingly if you're using your own web application.

Next, let's create a user to access the application we've just connected. Teleport has a built-in role called access that allows users to access cluster resources. Create a local user assigned this role:

tctl users add --roles=access alice

The command will output a signup link. Use it to choose a password and set up a second factor. After that, it will take you to the Teleport web UI.

Step 3/3. Access the application

There are a couple of ways to access the proxied application.

Every application is assigned a public address which you use to navigate to the application directly. In our sample Grafana application we have provided a public address with the --app-public-addr flag, so go to https://grafana.teleport.example.com (replace with your app public address) to access the app. If you're not logged into Teleport, you will need to authenticate before the application will show.

Alternatively, log into the Teleport Web Interface at https://teleport.example.com (replace with your proxy public address). All available applications are displayed on the Applications tab. Click on the Grafana application tile to access it.

Next steps

Dive deeper into the topics relevant to your Application Access use-case:

Learn in more detail about connecting applications with Application Access.
Learn about integrating with JWT tokens for auth.
Learn how to use Application Access with RESTful APIs.
See full configuration and CLI reference.

Have a suggestion or can’t find something?

IMPROVE THE DOCS