Skip to main content

Using JWT Authentication with Grafana

Report an issue with this page

This guide will help you configure Grafana JWT authentication 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 for a free trial or set up a demo environment.

  • 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:

      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.

  • 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.
  • 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 http://grafana.example.com:3000 to the domain of your Grafana instance:

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.

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​