teleport/docs/pages/application-access/getting-started.mdx

---
title: Getting Started with Teleport Application Access
description: Getting started with Teleport application access.
videoBanner: cvW4b96aPL0
---

This tutorial demonstrates how to configure secure access to an application 
through Teleport. The tutorial uses Grafana as a sample application because 
it's straightforward to install and run in a Docker container or Kubernetes cluster 
with no additional configuration required. If you want to configure access 
for a different web application, you can use this tutorial as a 
general guide for what to do. 

At a high level, configuring access for applications involves the following steps:

- Verify your environment meets the prerequisites.
- Verify you can launch the application in a Docker container, Kubernetes cluster, or 
  using another method.
- Generate a short-lived invitation token for the application to join the Teleport cluster.
- Install and configure Teleport on the application host.
- Add a user to verify access to the application.

## Prerequisites

For this tutorial, verify your environment meets the following requirements:

(!docs/pages/includes/edition-prereqs-tabs.mdx!)

- (!docs/pages/includes/tctl.mdx!)
- A host where you will run the Teleport Application Service.
- A Docker container or Kubernetes cluster to launch Grafana.

### Subdomains and applications

(!docs/pages/includes/dns-app-access.mdx!)

### Rights and permissions

This tutorial assumes that you have administrative rights for the Teleport cluster
and for the local computer, Docker container, or Kubernetes configuration where the
application runs.
   
The permissions used in this tutorial are intended for demonstration purposes.
Before running Teleport in a production environment, you should verify that you're 
following best practices to avoid security incidents.

(!docs/pages/includes/permission-warning.mdx!)

## Step 1/5. Generate a token

An invitation token is required to authorize a Teleport Application Service instance to
join the cluster. Generate a short-lived join token and save it on the host where 
you will run the Teleport Application Service. For example, you can generate the 
invitation token by running the following command on a server where the Teleport Auth 
Service runs:

```code
$ tctl tokens add \
    --type=app \
    --app-name=grafana \
    --app-uri=http://localhost:3000
```

Copy the output from this command and save the token in a separate file so it can be 
passed to the Teleport Application Service.

## Step 2/5. Start Grafana

You can start Grafana in a Docker container or Kubernetes cluster by following the 
appropriate steps.

<Tabs>
<TabItem label="Docker">

To start Grafana in a Docker container:

1. Open a terminal on a computer where Docker is installed.

1. Start Grafana by running the following command:

   ```code
   $ docker run --detach --name grafana --publish 3000:3000 grafana/grafana
   ```

1. Edit the `/etc/grafana/grafana.ini` file in the container to use the 
address for your Teleport cluster. 
   
   Under the `[server]` section, uncomment the `domain` key and set the value 
   to the address for your Teleport cluster. For example:
   
   ```code
   # The public facing domain name used to access grafana from a browser
   domain = teleport.example.com
   ```
   
   If you can't edit this file in the container, you can use the `sed` command to edit the file. 
   For example:

   ```code
   $ docker exec --user 0 grafana sed -i \
     's/;domain = localhost/domain = teleport.example.com/g' \
     /etc/grafana/grafana.ini
   ```

</TabItem>
<TabItem label="Kubernetes cluster">

If you install Grafana with the following `helm` instructions, it is available 
at `http://example-grafana.example-grafana.svc.cluster.local` in the 
Kubernetes cluster.

```code
$ helm repo add grafana https://grafana.github.io/helm-charts
$ helm repo update
$ helm install example-grafana grafana/grafana \
    --create-namespace \
    --namespace example-grafana
```
</TabItem>
</Tabs>

## Step 3/5. Install and configure Teleport

<Tabs>
<TabItem label="Docker">
Select a Teleport edition, then follow the [Installation](../installation.mdx) instructions 
for your environment.

To install on Linux:

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

1. Create the configuration file for Grafana at `/etc/app_config.yaml`
with a command similar to the following:
   
   ```code
   $ sudo teleport configure \
     --output=file \
     --proxy=<Var name="teleport.example.com" />:443 \
     --token=/tmp/token \
     --roles=app \
     --app-name=grafana \
     --app-uri=http://localhost:3000
   ```
     
   - Set the `--proxy` command-line option to the address for your Teleport cluster
(for example, `teleport.example.com` or `mytenant.teleport.sh`).
   - Set the `--token` command-line option to the file location on the Application 
Service host where you saved the invitation token that you generated earlier.
   - Change the `--app-name` and `--app-uri` command-line options if you're configuring 
access to a different web application.

(!docs/pages/includes/start-teleport.mdx service="the Teleport Application Service"!)
</TabItem>
<TabItem label="Kubernetes cluster">

(!docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx!)

Install the `teleport-kube-agent` Helm chart into your Kubernetes cluster to proxy Grafana
with a command similar to the following:

```code
$ JOIN_TOKEN=$(cat /tmp/token)
$ helm install teleport-kube-agent teleport/teleport-kube-agent \
  --create-namespace \
  --namespace teleport-agent \
  --set roles=app \
  --set proxyAddr=<Var name="teleport.example.com" />:443 \
  --set authToken=${JOIN_TOKEN?} \
  --set "apps[0].name=grafana" \
  --set "apps[0].uri=http://example-grafana.example-grafana.svc.cluster.local" \
  --set "labels.env=dev" \
  --version (=teleport.version=)
```

- Set `proxyAddr` to the address for your Teleport cluster (for example, 
`teleport.example.com` or `mytenant.teleport.sh`).
- Set `-authToken` to the invitation token that you previously generated.
- Change `apps[0].name` and `apps[0].uri` if you're configuring access to a different 
web application.

Make sure that the Teleport agent pod is running. You should see one
`teleport-kube-agent` pod with a single ready container:

```code
$ kubectl -n teleport-agent get pods
NAME                    READY   STATUS    RESTARTS   AGE
teleport-kube-agent-0   1/1     Running   0          32s
```

</TabItem>
</Tabs>

## Step 4/5. Create a user

Now that you have enrolled the application as a resource protected by Teleport, 
you can create a user to test access to the application.
Teleport has a built-in role called `access` that allows users to access cluster resources.

To assign to the `access` role to a new local user named `alice`, run the following command:

```code
$ tctl users add --roles=access alice
```

The command generates an invitation URL for the new user. You can use the URL to choose 
a password, set up a second factor for authentication, and sign in to the Teleport Web UI.

## Step 5/5. Access the application

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

Sign in to the Teleport Web UI using your Teleport cluster address. 
All available applications are displayed on the Applications tab. 
Click **Launch** on the Grafana application tile to access it.

Alternatively, you can call the application directly with its name as the subdomain, for example, 
`https://grafana.teleport.example.com` or `https://grafana.mytenant.teleport.sh`. 
You are prompted to sign in if you haven't already been authenticated.

## Next steps

Learn more about protecting applications with Teleport in the following topics:

- [Connecting applications](./guides/connecting-apps.mdx).
- Integrating with [JWT tokens](./jwt/introduction.mdx).
- Accessing applications with [RESTful APIs](./guides/api-access.mdx).
- Setting configuration options AND running CLI commands in the [Application Access reference](./reference.mdx).
- Using the Let's Encrypt [ACME protocol](https://letsencrypt.org/how-it-works/).