# Using JWT Authentication with Grafana

This guide will help you configure Grafana [JWT authentication](https://grafana.com/docs/grafana/latest/setup-grafana/configure-access/configure-authentication/jwt/) with Teleport.

## How it works

Teleport issues short-lived JWTs and injects them into each proxied request to Grafana. Grafana is configured to trust Teleport’s JWT signer, allowing it to verify the user’s identity and retrieve role information from the Teleport-signed token.

## Prerequisites

- A running Teleport cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md).

- The `tctl` and `tsh` clients.

  Installing `tctl` and `tsh` clients

  1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

     ```
     $ TELEPORT_DOMAIN=teleport.example.com:443
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     ```

  2. Follow the instructions for your platform to install `tctl` and `tsh` clients:

     **Mac**

     Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients:

     ```
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     In Finder double-click the `pkg` file to begin installation.

     ---

     DANGER

     Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

     ---

     **Windows - Powershell**

     ```
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```

     **Linux**

     All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md).

     ```
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     Teleport binaries have been copied to /usr/local/bin
     ```

* To check that you can connect to your Teleport cluster, sign in with `tsh login`, then verify that you can run `tctl` commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username:
  ```
  $ tsh login --proxy=teleport.example.com --user=email@example.com
  $ tctl status
  Cluster  teleport.example.com
  Version  19.0.0-dev
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
  ```
  If you can connect to the cluster and run the `tctl status` command, you can use your current credentials to run subsequent `tctl` commands from your workstation. If you host your own Teleport cluster, you can also run `tctl` commands on the computer that hosts the Teleport Auth Service for full permissions.
* Running [Application Service](https://goteleport.com/docs/enroll-resources/application-access/protect-apps/connecting-apps.md).
* Access to main config of your Grafana instance

## Step 1/3. Configure JWT authentication in Grafana

Add an `auth.jwt` section in Grafana’s main configuration file. Replace teleport.example.com with the domain name of your Teleport cluster:

```
[auth.jwt]
enabled = true

# HTTP header to look into to get a JWT token.
header_name = Authorization

# JSON Web Key Set (JWKS) URL from your Teleport cluster.
jwk_set_url = https://teleport.example.com/.well-known/jwks.json

# Teleport username can be found in "sub" or "username" claims.
username_claim = sub

# Map Teleport users to Grafana organization roles based on their Teleport
# roles. Adjust accordingly.
#
# In this example, if the user's Teleport role list (the "roles" claim) contains
# "editor", assign them the Grafana "Editor" role. All other users get the
# "Viewer" role.
#
# Teleport user traits are also available in the "traits" claim and can be
# used in expressions in the same way as roles.
role_attribute_path = contains(roles[*], 'editor') && 'Editor' || 'Viewer'

# auto-create users if they are not already matched.
auto_sign_up = true

```

Restart your Grafana instance after updating the config.

## Step 2/3. Register a Grafana application in Teleport

You can register the Grafana application in Teleport by defining it in your Teleport Application Service configuration, or by using dynamic registration with `tctl` or Terraform. Assign app URI to the domain of your Grafana instance:

**Static configuration**

Add an application entry in your Teleport Application Service configuration file, `teleport.yaml`:

```
app_service:
  enabled: true
  apps:
  - name: "grafana"
    uri: app URI
    rewrite:
      headers:
      - "Authorization: Bearer {{internal.jwt}}"

```

Restart the Teleport Application service.

**tctl**

Create an `app` resource definition file named `app-grafana.yaml`:

```
# app-grafana.yaml
kind: app
version: v3
metadata:
  name: grafana
spec:
  uri: app URI
  rewrite:
    headers:
    - name: "Authorization"
      value: "Bearer {{internal.jwt}}"

```

Create the `app` resource with:

```
$ tctl create -f app-grafana.yaml
```

**Terraform**

Create a `teleport_app` resource in terraform:

```
resource "teleport_app" "grafana" {
  version = "v3"
  metadata = {
    name = "grafana"
    labels = {
      "teleport.dev/origin" = "dynamic"
    }
  }

  spec = {
    uri = "app URI"
    rewrite = {
      headers = [{
        name  = "Authorization"
        value = "Bearer {{internal.jwt}}"
      }]
    }
  }
}

```

Apply the configuration:

```
$ terraform apply
```

The header rewrite configuration above will replace the `{{internal.jwt}}` template variable with a Teleport-signed JWT token in each request.

## Step 3/3. Connect to Grafana

Log in to your Teleport cluster in your browser at https\://teleport.example.com.

In the **Resources** tab, locate the `grafana` application and click **Launch**.

Grafana will open and you should be automatically logged in as your Teleport user. You can verify this by clicking your profile icon in the upper-right corner.

## Next steps

- Get more information about integrating with [Teleport JWT tokens](https://goteleport.com/docs/enroll-resources/application-access/jwt/introduction.md).
- See the [dynamic registration](https://goteleport.com/docs/enroll-resources/application-access/configuration/dynamic-registration.md) guide.
- Learn more about [accessing APIs](https://goteleport.com/docs/enroll-resources/application-access/protect-apps/api-access.md) with the Teleport Application Service.
- Take a look at application-related [Access Controls](https://goteleport.com/docs/enroll-resources/application-access/configuration/controls.md).